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WARNING  -  PRE-RELEASE  SOFTWARE! 
USE  CAUTION! 


Pre-release  versions  of  the  dBASE  IV™  Developer's  Edition  are  not  intended  for  operation 
by  an  end  user,  but  are  made  available  for  the  purposes  of  evaluation  and  testing  only.  In 
pre-release  form,  the  software  is  likely  to  contain  "bugs"  and  may  behave  in  an 
unpredictable  manner.  The  possibility  that  the  software  may  corrupt  or  destroy  data  without 
warning  exists,  and  therefore  caution  should  be  taken  to  isolate  this  pre-release  software 
from  other  software  and  critical  data. 

In  addition  to  all  the  standard  features  of  dBASE  IV,  the  dBASE  IV  Developer's  Edition 
contains  a  number  of  tools  for  advanced  users  and  application  developers.  The  final  release 
of  the  dBASE  IV  Developer's  Edition  will  include  a  RunTime  module  (not  included  in  pre¬ 
release  versions)  which  will  permit  the  unlimited  distribution  of  executable  applications. 

See  the  brochures  enclosed  with  this  documentation  for  additional  details  on  these  products. 
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-HI- INTRODUCTION 

dBASE  IV  offers  a  complete  Applications  Generator  and  forms, 
reports,  and  query  generators.  For  more  sophisticated  or 
customized  applications,  however,  you  might  want  to  write  dBASE 
programs  yourself.  This  book  is  a  reference  to  programming  in 
dBASE  IV. 

H2-WHO  SHOULD  READ  THIS  MANUAL 

This  manual  in  intended  for  novice  to  advanced  dBASE  programmers. 
For  the  novice.  Chapter  1  provides  a  brief  tutorial  and 
orientation  to  the  book.  Chapters  2  and  3  describe  how  to  use  the 
program  editor  and  memory  variables. 

For  the  developer  building  applications  for  in-house  or  external 
distribution,  Chapters  4  and  5  outline  how  to  design  a  sound 
application.  Chapters  16  through  18  discuss  how  to  ensure  the 
security  and  integrity  of  the  data,  test  and  debug  an 
application,  and  prepare  distribution  disks  and  user 
documentation . 

For  all  users.  Chapters  6  through  19  provide  many  code  examples 
covering  the  main  parts  of  a  typical  application:  setup,  user 
interface,  input,  data  processing,  and  code.  The  examples  in  the 
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manual  come  primarily  from  the  Business. prg  application  provided 
with  your  sample  files.  The  application  itself  contains  several 
programs . 

-H2-WHAT  YOU  SHOULD  ALREADY  KNOW 

In  order  to  get  the  most  out  of  this  book,  you  should  be  familiar 
with  the  dBASE  IV  Control  Center.  You  should  know  how  to  create  a 
database  file  and  build  screen  forms,  reports,  labels,  and 
queries  (unless  you  plan  to  code  these  totally  from  scratch) . 

You  should  also  be  familiar  with  dBASE  IV  at  the  dot  prompt.  That 
doesn't  mean  you  have  to  read  Language  Reference  from  cover  to 
cover,  but  you  should  be  comfortable  doing  everyday  file 
management  tasks,  such  as  INDEXing  a  database  file  and  LISTing 
data,  at  the  dot  prompt. 

Here  are  some  things  you  don't  need  to  know  before  using  this 
book.  You  don't  need  to  know  how  to  program  in  any  other 
language.  You  don't  need  to  know  how  to  use  the  entire  dBASE  IV 
menu  system  (as  long  as  you  can  accomplish  equivalent  tasks  at 
the  dot  prompt) .  You  don't  need  to  know  how  to  use  the  dBASE  IV 
Applications  Generator. 
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-NOTE-If  you're  eager  to  create  programs  in  dBASE  IV  and  you 
don't  want  to  bother  with  command  syntax  just  yet,  the 
Applications  Generator  lets  you  develop  very  sophisticated 
programs  without  writing  any  code.  See  Using  the  dBASE  IV 
Applications  Generator  for  more  information. -ENDBOX- 

-H2-H0W  TO  USE  THIS  BOOK 

This  manual  isn't  meant  to  be  read  from  cover  to  cover.  It  is  a 
reference  book,  so  use  it  to  look  up  specific  tasks  that  you  want 
your  program  to  accomplish. 

This  book  consists  largely  of  code  fragments,  small  sections  of 
code  lifted  out  of  a  larger  program.  Providing  code  fragments 
rather  than  full  programs  permits  the  inclusion  of  many  more 
examples.  To  see  these  code  fragments  in  context,  refer  to  the 
Sample  Programming  Code  booklet,  which  contains  the  complete 
code. 


To  get  the  most  out  of  this  book,  refer  to  Language  Reference 
whenever  you  are  not  entirely  clear  about  how  a  command  or 
function  used  in  a  code  example  works. 

-H2-WHAT  THIS  BOOK  IS  ABOCT 
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This  book  is  a  compilation  of  useful  dBASE  IV  programming 
information  and  code  examples.  It  is  organized  by  task  for  easy 
reference. 

Here  is  a  list  of  the  major  topics  covered  in  this  book: 

-o-How  to  program  in  dBASE  —  a  brief  tutorial  (Chapter  1) 

-o-How  to  use  the  dBASE  IV  program  editor  (Chapter  2) 

-o-How  to  use  memory  variables  (Chapter  3) 

-o-How  to  conduct  a  needs  analysis  and  design  the  database  system 
underlying  your  application  (Chapter  4) 

-o-How  to  design  the  basic  architecture  of  a  program,  and  how  to 
use  procedures  to  maxiiize  program  efficiency  (Chapter  Li) 

-o-How  to  write  the  main  program  of  your  application  (Chapter  6) 

-o-How  to  provide  windows,  boxes,  menus,  lists,  and  ocher  visual 
effects  with  your  application  (Chapters  7  and  8) 

-o-How  to  handle  data  input,  processing,  and  output  (Chapters  9 
through  15) 

-o-How  to  ensure  file  security  and  integrity  (Chapter  16) 
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-o-How  to  taat  and  debug  your  application  (Chapter  17) 

-o-How  to  distribute  and  support  your  application  (Chapter  18) 

The  companion  Sample  Programming  Code  booklet  provides  the 
complete  coda  for  the  sample  applications  provided  with  dBASE  IV. 

— H2 -CONVENTIONS 

This  book  uses  a  number  of  conventions  of  which  you  should  be 
aware . 

-o-dBASE  commands  and  functions  are  printed  in  all  upper  case. 

-o-The  names  of  files,  fields,  index  tags,  and  procedures  are 
printed  with  an  initial  capital  letter.  The  names  of  memory 
variables,  windows,  and  menus  are  printed  in  all  lower  case.  This 
convention  reflects  the  different  ways  these  entities  are  handled 
by  dBASE  IV. 

-o-New  terms,  book  titles,  and  the  names  of  memory  variables, 
windows,  and  menus  are  printed  in  italics. 

-o-Program  code  is  printed  in  a  special  typeface,  so  that  the 
characters  align  exactly  as  they  do  on  your  screen. 
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-o-Variations  on  a  code  fragment  are  shown  preceded  by  the  entry 
Variation  in  italic  type. 

-o-Comments  in  the  code  are  preceded  by  an  asterisk  (*)  if  the 
note  is  on  a  separate  line,  or  a  double  ampersand  (&&)  if  the 
note  is  on  the  same  line  as  the  code . -ENDLIST- 

-COMMENT-Special  Comment  Sections 

You'll  find  some  information  in  special  comment  sections.  The 
icon  shown  here  sets  the  material  in  these  commentaries  apart 
from  other  text  on  the  page.  (The  icon  is  also  the  dBASE  symbol 
for  adding  a  comment  to  a  line  of  code.) 

The  purpose  of  these  special  comment  sections  is  to  save  you 
reading  time.  You  can  decide  depending  upon  your  programming 
background  and  your  purpose  at  the  time  whether  you  want  to  read 
a  given  comment  section  by  a  quick  glance  at  its  title.  If  you 
choose  to  skip  over  the  material,  a  single  horizontal  line  at  the 
end  of  the  section  tells  you  where  the  chapter  text  picks  up 
again. -ENDCOM- 
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dBASE  IV  has  two  editors,  the  word-wrap  editor  and  the  layout 
editor.  The  word-wrap  editor  doubles  as  the  program  editor,  and 
has  capabilities  of  special  interest  to  programmers. 

-H2-WHAT  THIS  CHAPTER  COVERS 

This  chapter  discusses  those  aspects  of  the  dBASE  IV  program 
editor  that  are  of  particular  interest  to  programmers.  You'll 
read  about  the  following  topics: 

-o-Accessing  the  program  editor 

-o-Operating  the  program  editor 

-o-Special  features  of  the  program  editor-ENDLIST- 

-NOTE-This  chapter  does  not  explain  the  basic  operation  of  the 
program  editor  in  detail.  If  you  are  not  familiar  with  the  dBASE 
IV  word-wrap  editor,  please  read  Chapter  4  of  Using  the  Menu 
System  before  continuing  with  this  chapter. -ENDBOX- 


-H2-ACCESSING  THE  PROGRAM  EDITOR 

You  can  open  the  program  editor  either  from  the  dot  prompt  or  in 
the  Control  Center: 
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-o-At  the  dot  prompt,  enter  MODIFY  COMMAND  <tllename>  (or  MODI 
COMM  <filename>) ,  where  <filename>  is  the  name  of  the  program 
file  you  want  to  create  or  edit.  dBASE  automatically  supplies  the 
.prg  extension. 

If  the  file  you  specify  already  exists,  dBASE  IV  opens  it  in  the 
program  editor  (see  Figure  2-1).  Otherwise,  it  creates  a  new  file 
and  displays  a  blank  editor  screen. 

-o-In  the  Control  Center,  choose  a  program  file  to  edit  from  the 
Applications  panel.  Then  select  Modify  application  from  the  panel 
prompt  box  that  appears.  To  create  a  new  program  file,  choose 
<create>  from  the  panel  and  then  dBASE  program  from  the 
box . -ENDLIST- 

-ILLUS-Figure  2-l\mThe  program  editor- ENDFIG- 

-NOTE-You  can  have  dBASE  IV  open  your  own  word  processor  instead 
of  the  built-in  editor.  Just  add  the  statement  TEDIT  = 

<vord  processor >  to  your  Config.db  file.  See  chapter  6  of 
Language  Reference  for  more  information  on  Config.db. 

While  the  dBASE  IV  editor  automatically  deletes  old  object  (.dbo) 
files  when  you  modify  a  program  and  recompiles  the  source  (.prg) 
file,  external  editors  do  not  do  this.  Therefore,  SET  DEVELOPMENT 
ON  or  include  the  statement  DEVELOPMENT  »  ON  in  your  Config.db 
file  if  you  are  using  an  external  editor.  This  command  instructs 
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dBASE  IV  to  compare  the  creation  dates  and  times  of  the  .prg  and 
■dbo  files,  and  to  recompile  the  .prg  file  if  the  .dbo  file  is 
older. -ENDBOX- 

-H2-OPERATITG  THE  PROGRAM  EDITOR 

This  section  summarizes  the  operation  of  the  dBASE  IV  program 
editor.  See  Chapter  4  of  Using  the  Menu  System  for  a  more 
detailed  description  of  its  operation. 

-H3~Navigating  the  Program  Editor 

Table  2-1  lists  the  pre-defined  cursor  navigation  and  editing 
keys  of  the  program  editor. 


-TABLE-Table  2-l\mProgram  editor  navigation  and  editing  keys 


Key 


Action 


Arrow  keys  Move. cursor  up,  down,  left,  right 

-CONTROL - LA-  or  Move  cursor  left  or  right  one  word 


-CONTROL - RA- 

-HOME-  or  -END-  Move  cursor  to  beginning  or  end  of  line 

-PGUP-  or  -PGDN-  Move  cursor  up  or  down  one  screen 

-CONTROL - PGUP-  or  Move  cursor  to  beginning  or  end  of  file 

-CONTROL - PGDN- 

-TAB-  or  Move  cursor  to  next  or  previous  tab  stop1 


-SHIFT - TAB- 
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-DEL- 


Delete  selected  item1 2 


-BACKSPACE-  or 


Delete  previous  character  or  word 


-CONTROL - BKSP- 


-CONTROL - T~ 


Delete  to  end  of  word 


-CONTROL - Y~ 


Delete  current  line 


-INS- 


Toggle  between  insert  and  overwrite  modes 


-CONTROL RETURN-  Save  work  and  stay  in  program  editor 

-CONTROL - END-  Save  work  and  exit  program  editor 


-ESCAPE- 


Abandon  work  and  exit  program  editor 


1.  If  the  cursor  is  in  the  outdent  (the  margin  to  the  left  of 

indented  code) ,  pressing  -SHIFT - TAB-  resets  the  left  margin  to 

the  cursor  position. 

2.  Use  -F6  SELECT-  to  select  more  than  one  character . -ENDTABLE- 

-H3-The  Program  Editor  Menus 

The  program  editor  provides  five  menus  for  convenient  operation: 

-o-The  Layout  menu  lets  you  open  and  save  files. 

-o-The  Words  menu  lets  you  position  text,  modify,  hide,  or 
display  the  ruler,  enable  or  disable  automatic  indent,  add  or 
remove  lines,  insert  page  breaks,  and  read  or  write  text  files. 
(The  Display  and  Style  submenus  of  this  menu  are  not  accessible 
from  the  program  editor.) 
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-o-The  Go  To  menu  lets  you  move  to  a  specific  line  in  your 
program,  or  search  and  replace  text  strings. 

-o-The  Print  menu  lets  you  adjust  print  settings  and  print  your 
program. 

-o-The  Exit  menu  lets  you  exit  the  editor  and  run  or  debug  the 
program  you  are  editing. -ENDLIST- 

Set  the  left  margin  (indentation)  with  the  Modify  ruler  option  of 
the  Words  menu.  The  default  left  margin  is  0.  The  right  margin  in 
the  program  editor  is  fixed  at  1024  characters.  Set  tabstops  with 
the  _tabstops  system  memory  variable  (see  Chapter  5  of  Language 
Reference) . 

Each  line  of  your  program  inherits  the  settings  of  the  previous 
line  until  you  make  a  change.  You  can  also  indent  code 
automatically  (see  next  section) . 

-H2 -SPECIAL  FEATURES  OF  THE  PROGRAM  EDITOR 

The  dBASE  IV  program  editor  has  several  features  designed 
specifically  with  programmers  in  mind.  You  can  now: 


-o-Edit  indefinitely  large  files. 

-o-Type  and  edit  lines  up  to  1,024  characters  long. 
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-o-Indent  code  automatically. 

-o-Move  and  copy  large  blocks  of  code. 

-o-Run  and  debug  your  program  directly  from  the  program 
editor. -ENDLIST- 

-H3-Editing  Large  Files 

The  dBASE  III  PLUS-TR-  MODIFY  COMMAND  editor  could  only  edit 
files  smaller  than  5,000  bytes.  This  limit  has  been  significantly 
increased  in  dBASE  IV.  You  can  now  edit  indefinitely  large 
program  files  (limited  only  by  your  available  memory)  containing 
up  to  12,000  lines  of  coce. 

-H3 -Typing  Long  Lines  of  Code 

Unlike  previous  versions  of  dBASE,  dBASE  IV  lets  you  type  and 
edit  lines  of  code  up  to  1,024  characters  long.  In  the  program 
editor,  use  the  -HOME-  and  -END-  keys  to  jump  quickly  to  the 
beginning  or  end  of  a  line. 

If  you'd  rather  break  up  long  command  lines  into  several  shorter 
lines,  type  a  semicolon  (;)  at  the  end  of  each  command  line 
segment  except  the  last  one.  dBASE  reads  the  semicolon  as  a  line 
continuation  character. 
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-NOTE-SQL  reads  a  semicolon  as  an  instruction  to  enter  the 
preceding  command  rather  than  as  a  continuation  character.  SQL 
does  not  require  a  continuation  character  for  commands  entered  on 
more  than  one  line. -ENDBCX- 

-H3~Editing  a  Program  in  a  Window 


You  can  operate  the  program  editor  in  a  user-defined  window.  This 
means  you  can  view  your  code  in  a  window  while  running  the 
program  next  to  it.  You  can  also  display  two  different  sections 
of  code  at  the  same  time,  or  work  at  the  dot  prompt  while  editing 
a  program  in  a  window. 

The  following  dot  prompt  commands  define  a  window  and  then  open 
the  program,  editor  in  the  window.  The  named  file  displays  in  the 
editor. 

-M-.  -I-DEFINE  WINDOW  progedit  FROM  <0,0>  TO  <12,79>-L- 
.  ACTIVATE  WINDOW  progedit-L- 

.  MODIFY  COMMAND  <filename>  WINDOW  progedit-N- 

Chapter  7  discusses  the  dBASE  IV  window  building  commands. 

-H3-Indenting  Code  Automatically 
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To  improve  the  readability  of  your  programs,  indent  the  lines  of 
code  that  fall  within  programming  constructs.  (Chapter  5 
discusses  the  dBASE  IV  programming  constructs.)  For  example,  in 
the  following  routine,  the  lines  of  code  between  the  SCAN  and 
ENDSCAN  commands  are  indented  three  spaces. 

-M-USE  Goods  ORDER  Vendor_id-L- 
mvend_id  =  "2100"~L- 
SEEK  mvend_id-L- 
CLEAR-L- 

SCAN  ALL  WHILE  Vendor_id  =  mvend_id-L- 

LIST  OFF  NEXT  10  Part_name,  Cost  WHILE  Vendor_id  =  "2100"-L- 
WAIT  TO  manswer-L- 
CLEAR-L- 
ENDSCAN-N- 

The  dBASE  IV  program  editor  has  an  automatic  indentation  feature 
that  is  very  helpful  when  you're  typing  indented  code.  If  Enable 
automatic  indent  is  set  to  YES  (the  default)  in  the  Words  menu, 
the  program  editor  defines  the  left  margin  and  indentation 
according  to  the  position  of  the  first  non-space  character  on  the 
line.  Ensuing  lines  of  code  inherit  the  setting. 

To  type  the  indented  lines  in  the  above  code  example,  be  sure 
automatic  indentation  is  on  and  then  use  -SPACEBAR-  to  insert 
three  blank  spaces  before  the  LIST  command.  When  you  start  typing 
the  command,  note  that  the  first  #  symbol  on  the  ruler  line  moves 
to  position  4.  Press  -RETURN-  at  the  end  of  the  command  line.  The 
cursor  automatically  goes  to  position  4  on  the  next  line.  Type 
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tha  remaining  two  indented  lines.  Finally,  press  -SHIFT - TAB-  at 

the  beginning  of  the  ENDSCAN  command  line  to  reposition  the 
cursor  at  the  left  margin. 


You  can  also  change  the  indentation  of  several  lines  together, 
maintaining  their  relative  indentation.  To  do  this,  select  the 
lines  you  want  to  change  with  -F6  SELECT-.  Then  reposition  the 
outermost  #  symbol  on  the  ruler  line  (accessed  through  Modify 
command) .  The  block  of  code  adjusts  without  losing  its  relative 
indentation,  and  the  other  #  symbols  are  repositioned 
automatically. 

-H3-Moving  and  Copying  Blocks  of  Code 

dBASE  IV  lets  you  move  and  copy  blocks  of  code  in  the  program 
editor.  Just  select  the  code  with  -F6  SELECT-,  move  the  cursor  to 
the  desired  position,  and  press  -F7  MOVE-  or  -F8  COPY-. 

The  main  purpose  for  moving  code  in  a  program  is  to  reorganize  a 
program.  For  example,  you  might  discover  that  you're  using  the 
same  routine  in  several  places  throughout  a  program.  To  save 
memory  and  make  the  program  run  more  quickly,  block  move  one 
instance  of  the  redundant  routine  to  a  separate  procedure  and 
delete  all  other  occurrences  of  it.  Replace  each  instance  of  the 
routine  with  the  command  DO  <procadure  name> . 
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Copying  a  block  of  code  is  useful  if  you  want  to  use  similar,  but 
not  identical,  code  somewhere  else  in  your  program.  Copy  the 
routine  to  the  desired  location  and  then  make  the  necessary 
modifications.  You  can  also  copy  routines  to  separate  procedure 
files,  to  build  procedure  libraries  for  use  in  future 
applications. 

-H3 -Running  and  Debugging  in  the  Program  Editor 

You  can  both  run  and  debug  your  programs  from  within  the  program 
editor.  To  do  this,  choose  Run  program  or  Debug  program  from 
the  Exit  menu.  dBASE  IV  automatically  saves  any  changes  you've 
made  before  running  the  program. 

when  you  edit  a  program  file,  the  program  editor  automatically 
makes  a  backup  copy  of  the  file  with  the  extension  .bak.  You  can 
reclaim  this  file  if  you  need  to  by  changing  the  extension  to 
•prg. 
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-Hl-MEMORY  VARIABLES 

dBASE  stores  temporary  or  working  data  in  memory  vsurlablas.  You 
should  understand  how  memory  variables  work  before  you  begin 
programming  in  dBASE. 

-H2-WHAT  THIS  CHAPTER  COVERS 

This  chapter  provides  a  brief  overview  of  memory  variables  and 
memory  variable  arrays.  It  discusses  the  following  topics: 

-o-what  memory  variables  are 

-o-Initializing  memory  variables  and  memory  variable  arrays 
-o-Using  memory  variables  and  memory  variable  arrays 
-o-Declaring  memory  variables  and  arrays  PUBLIC  or  PRIVATE 
-o-Deleting  memory  variables  and  arrays  from  memory 
-o-Using  memory  variable  files 
-o-Macro  substitution-ENDLIST- 
-H2-ABOUT  MEMORY  VARIABLES 

A  memory  variable  is  a  temporary  storage  location  for  data.  The 
data  in  a  memory  variable  is  stored  in  memory,  with  a  name  that 
references  its  location  (see  Figure  3-1) . 

-ILLUS-Figure  3-l\mMemory  variables-ENDFIG- 

Memory  variables  can  contain  numbers,  character  strings,  a  date, 
or  a  logical  value  (,T.  or  .F.).  There  are  no  memo  type  memory 
variables. 

Programs  use  memory  variables  for  many  purposes.  For  example,  a 
memory  variable  can  hold  user-entered  data  for  validation, 
working  data  for  computation,  or  a  frequently  used  screen  prompt 
for  display. 

You  refer  to  a  memory  variable  by  its  name,  not  its  contents.  You 
can  therefore  vary  the  contents  without  changing  the  name.  This 
means  that  you  can  use  the  same  memory  variable  repeatedly 
throughout  a  program. 

-NOTE-Throughout  this  book,  the  names  of  memory  variables  are 
shown  in  Italics  to  distinguish  them  from  field  names . -ENDBOX- 

-H2- INITIALIZING  MEMORY  VARIABLES 
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To  initialize  a  memory  variable,  name  the  variable  and  store  data 
in  it.  dBASE  automatically  assigns  the  variable  the  data  type  of 
the  data  that  you  put  in  it. 

Initializing  a  memory  variable  overwrites  any  existing  memory 
variable  with  the  same  name.  Therefore,  to  modify  a  memory 
variable,  just  reassign  it.  The  data  type  of  the  variable  will 
reflect  the  new  data. 

-COMMENT-Naming  memory  variables 

The  name  of  a  memory  variable  may  be  up  to  ten  characters  long. 

It  may  include  letters,  numbers,  and  underscores,  but  no  blank 
spaces.  Start  the  name  with  a  letter,  and  avoid  using  dBASE 
reserved  words  (command  and  function  names) . 

Here  are  some  tips  on  effective  naming  of  memory  variables: 

Choose  a  name  that  describes  what  the  memory  variable  does,  such 
as  -I-mcost-R-  to  describe  a  variable  holding  cost  data.  If  the 
variable  corresponds  to  a  field  in  the  database  file,  give  it  a 
similar  name.  Start  memory  variable  names  with  the  letter  -I-m-R- 
or  the  characters  -I-m  -R-  ,  to  prevent  confusion  with  an 
identical  field  name.  If  you  need  all  ten  characters  for  variable 
names,  use  the  pointer,  -t-m->-R-  to  distinguish  the  variables 
from  fields  of  the  same  name.  For  example,  the  field  Qty_onhand 
would  become  the  variable  -I-m->qty_onhand~R- . 

If  you  like,  indicate  the  data  type  of  the  variable,  and  whether 
it  is  global  or  local,  in  its  name.  For  example,  the  name 
-I-lc  title-R-  suggests  a  local  character  variable  holding  a 
title. -ENDCOM- 

You  can  initialize  memory  variables  in  two  ways: 

-o-Using  the  STORE  command:  STORE  "Exit?  Y/N"  TO  promptl 

-o-Using  the  equivalent  assignment  statement : 
promptl  =  "Exit?  Y/.V-ENDLIST- 

Use  STORE  to  initialize  several  memory  variables  at  once 
-M-STORE  0.00  TO  subtotal , totals, cash-N- 

Table  3-1  shows  some  typical  memory  variable  definitions.  Note 
that  character  strings  are  delimited,  and  dates  are  converted  to 
date  type  c-ata  with  the  CT0D()  function  or  its  equivalent, 

{  /  /  ). 

-TABLE -Table  3-l\mInitializing  memory  variables 

Type  Definition 

Character  mfirstname  -  "Weston" 

promptl  =■  "That's  incorrect  ...  try  again" 
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STORE  SPACE (20)  TO  mlastname 

STORE  "  "  TO  choice,  answer 

Numeric 

part  qty  -  0 
mcost  =  0.00 

STORE  0.00  TO  subtotal , total , cash 

Date 

today  -  DATE() 

birthday  =■  CTOD("ll/13/85") 

date_trans  *  (  /  /  ) 

Logical 

finished  -  .T. 

STORE  .F.  TO  erased,  not_valid-ENDTABLE- 
-H2- INITIALIZING  MEMORY  VARIABLE  ARRAYS 

A  memory  variable  array  is  a  matrix  of  memory  variables  arranged 
in  rows  and  columns.  Memory  variable  arrays  can  be  either  one-  or 
two-dimensional.  A  one-dimensional  array  has  only  one  column, 
whereas  two-dimensional  arrays  have  two  or  more  columns.  The 
total  number  of  elements  in  an  array  is  equal  to  the  number  of 
rows  times  the  number  of  columns  (see  Figure  3-2) . 

-ILLUS-Figure  3-2\mOne  and  two-dimensional  arrays-ENDFIG- 

To  initialize  a  memory  variable  array,  DECLARE  the  array 
structure  and  then  assign  memory  variables  to  the  elements. 

(Array  and  element  names  follow  the  same  naming  conventions  as 
memory  variables  —  see  previous  comment  box.) 

Refer  to  an  array  element  by  the  name  of  the  array  followed  by 
the  element  coordinates  (row  and  column  numbers)  in  square 
brackets.  You  can  STORE  different  types  of  data  TO  different 
elements  in  a  single  array.  Each  element  has  a  data  type,  but  the 
array  as  a  whole  does  not. 

The  following  example  prints  an  array  showing  part  number  and 
cost  for  each  record  in  the  Goods  database  file: 

-M-USE  Goods  ORDER  Vendor_id-L~ 

DECLARE  vend_aray [ 33 , 2 ] -L~ 

rrow  *  1-L- 

SCAN-L- 

vend_aray[rrow, 1]  »  Goods->Part_id-L- 
vend  aray[rrow,2]  -  Goods->Cost-L- 

?  "Part  no.",  vend_aray [rrow, 1] ,  "Cost",  vend_aray[rrow,2]-L- 
rrow  »  rrow  +  1-L- 
ENDSCAN-N- 

You  can  STORE  a  memory  variable  to  an  array,  and  also  STORE  the 
contents  of  one  array  element  to  another.  Initializing  a  memory 
variable  with  the  same  name  as  an  array  overwrites  the  array 
definition. 
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-H2-USING  MEMORY  VARIABLES  IN  PROGRAMS 

Table  3-2  shows  some  of  the  typical  ways  in  which  memory 
variables  are  used  in  programs. 

-TABLE-Table  3-2\mUsing  memory  variables  in  programs 


Purpose  Example 

Handle  screen  messages  answer  ■  . T. 

?rn  warn  -  "Printer  not  ready" 
"Ts  printer  ready?  (Y/N)" 


Hold  data  for  validation  mpart_id  »  SPACE (10) 

and  entry  into  .dbf  file  8...SAY  "Enter  part  no."  GET  mpart_id 

*  Check  for  duplicate  part  number 
DO  Chk_dup  WITH  mpart_id 


Hold  data  for  searching  mpart_id  »  SPACE (10) 

@ . . . SAY  "Enter  part  no."  GET  mpart_id 
SEEK  mpart_id 

Hold  data  for  processing  maxx  -  100 

6...SAY  "Enter  order  quantity"  ; 

GET  m->qty  2order 
IF  m->qty_2order  >  maxx 

?  "Quantity  ordered  is  too  large" 
ENDIF 


Hold  data  for 
computation 


Hold  data  for  report 
filters 


STORE  3.00  TO  oldbalance,  amt_lstbil,  ; 
amt  1st  pd 

S...SAY  "Enter  amount  of  last  bill"  ; 

GET  m->amt_lstbil 
@ . . .  SivY  "Enter  amount  last  paid"  ; 

GET  m->amt_lst_pd 

oldbalance  =*  amt_lstbil  -  amt_lst_pd 

m->date  hired  «  {  /  /  ) 

Q...SAY  "Enter  earliest  hire  date"  ; 

GET  m->date  hired 
READ 

SET  FILTER  TO  Date  hired  =•  ; 
m->date  hired-ENCTABLE- 


-H2-PDBLIC  AND  PRIVATE  VARIABLES 


dBASE  IV  provides  two  classes  of  memory  variable:  PUBLIC  and 
PRIVATE.  A  PUBLIC  variable  is  available  in  all  program  modules, 
no  matter  where  you  initialize  it.  A  PRIVATE  variable  operates 
only  in  the  module  where  you  initialize  it  and  all  subordinate 
modules. 
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In  Figure  3-3,  balance  is  available  in  all  programs,  even  though 
it's  declared  PUBLIC  in  a  subprogram.  However,  m  amount  is 
available  only  in  the  program  where  it  is  initialized  and  in  all 
dependent  subprograms.  The  m_cash  variable  is  available  in  one 
subprogram  only. 

-ILLUS-Figure  3-3\mPUBLIC  and  PRIVATE  variables-ENDFIG- 

In  dBASE  programs,  memory  variables  are  PRIVATE  unless  you 
declare  them  PUBLIC.  So  if  you  initialize  the  variable  in  a 
subprogram,  it  will  be  PRIVATE  to  that  subprogram  and  all 
programs  that  it  calls.  dBASE  IV  releases  the  variable  when  the 
subprogram  RETURNS  control  to  the  calling  program. 

If  you  want  to  hide  a  variable  from  a  higher-level  variable  of 
the  same  name,  however,  you  must  explicitly  declare  it  PRIVATE. 
This  lets  you  use  standard  names  for  variables  that  do  the  same 
thing  throughout  your  program. 

For  example,  in  Figure  3-4,  you  can  use  the  PRIVATE  balance 
variable  in  the  Subl  subroutine  and  in  any  subprogram  that  it 
calls.  When  program  control  RETURNS  to  the  original  module,  the 
variable  automatically  reclaims  its  original  value  of  3b0.00. 

Here  is  the  code  to  initialize  the  PRIVATE  balance  variable: 

-M-PRIVATE  balance- L- 
balance  -  175.00-N- 

- ILLUS-Figure  3-4\mHiding  a  PUBLIC  variable-ENDFIG- 

Since  dBASE  memory  variables  are  PRIVATE  by  default,  you  need  to 
declare  them  PUBLIC  except  in  the  main  (top-level)  program 
modula.  dBASE  IV  never  clears  PUBLIC  variables  unless  explicitly 
told  to  do  so  (see  next  section) . 

To  initialize  a  PUBLIC  memory  variable,  first  declare  it  PUBLIC 
and  then  initialize  its  contents. 

-M-PUBLIC  ba lance- L- 
balance  “  350.00-N- 

-H2-RE LEASING  MEMORY  VARIABLES  FROM  MEMORY 

dBASE  clears  all  PRIVATE  memory  variables  automatically  when  a 
program  finishes,  or  when  the  subprogram  where  they  were 
initialized  terminates.  However,  PUBLIC  variables  must  be 
explicitly  CLEARed  or  RELEASEd. 

Use  the  RELEASE  command  to  erase  specified  memory  variables  and 
arrays  from  memory.  Use  CLEAR  ALL  or  CLEAR  MEMORY  to  erase  all 
variables  at  once.  QUITting  dBASE  automatically  erases  all 
variables  in  memory. 
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Table  3-3  shows  some  different  ways  to  erase  memory  variables 
from  memory.  Use  the  same  commands  to  erase  memory  variable 
arrays. 

-TABLE-Table  3-3\mErasing  memory  variables 


Operation 

Erase  a  single  memory  variable 
Erase  more  than  one  variable 
Erase  all  variables  with  names 
starting  with  m1 
Erase  all  variables  except 
with  names  starting  with  m1 
Erase  all  PUBLIC  variables 


Example 

RELEASE  mcost 
RELEASE  mcost,  mbalance 
RELEASE  ALL  LIKE  m* 

RELEASE  ALL  EXCEPT  m* 

CLEAR  MEMORY  or  CLEAR  ALL 


T.  RELEASE  ALL  LIKE/EXCEPT  does  not  erase  PUBLIC  variables.  Only 
CLEAR  MEMORY,  CLEAR  ALL,  or  RELEASE  <variables>  erase  PUBLIC 
variables . -ENDTABLE- 

-WARNING- Because  you  might  inadvertently  clear  variables  that  you 
want  to  keep,  be  careful  when  using  CLEAR  MEMORY  or  CLEAR 
ALL.-ENDBOX- 


-H2-0SING  MEMORY  FILES 


If  you  plan  to  reuse  memory  variables,  SAVE  them  to  a  memory 
file.  Later,  you  can  RESTORE  then  to  active  memory  frou  the 
memory  file.  dBASE  gives  all  memory  files  the  extension  .mem. 

The  following  dot  prompt  commands  initialize  several  memory 
variables  and  a  memory  variable  array,  and  then  SAVE  the 
definitions  to  the  fill  Setup. mem: 

.  STORE  SPACE (20)  TO  mlastname,  mfirstname 
.  STORE  "  "  TO  cust_id,  emp_id,  part_id,  po_number 
.  part_qty  =»  0 
.  date^trans  -  (  /  /  ) 

.  invoiced  =■  .  F. 

.  SAVE  TO  Setup 

.  STORE  0  TO  vend_aray [ 1 , 1 ] ,  vend_ aray[2,l] ,  vend_aray(2 , 2] 

Use  the  RESTORE  command  to  read  the  contents  of  a  memory  file 
back  into  memory.  Both  individual  variables  and  memory  variable 
arrays  will  be  RESTOREd  to  memory  as  defined. 

To  RESTORE  the  contents  of  Setup. mem  but  not  RELEASE  any  other 
variables  in  memory,  enter  the  command: 

-M-RESTORE  FROM  Setup  ADDITIVE-N- 
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-WARNING-When  you  RESTORE  memory  variables  from  a  file,  you 
automatically  RELEASE  all  variables  currently  in  memory  unless 
you  instruct  dBASE  IV  to  retain  them  (with  the  ADDITIVE 
clause) . -ENDBOX- 

dBASE  does  not  save  the  PUBLIC/PRIVATE  status  of  a  variable  to 
the  memory  file.  If  you  RESTORE  a  memory  file  within  a  program, 
the  variables  come  back  PRIVATE  (the  default  status) .  Use  the 
PUBLIC  command  to  make  them  PUBLIC: 

-M-PUBLIC  mlastname,  mf irstname-L- 
RESTORE  FROM  Setup  ADDITIVE-N- 

You  can  add  variables  to  an  existing  memory  file  and  delete 
variables  from  it.  At  the  dot  prompt,  RESTORE  the  memory  file. 
Then  initialize  any  additional  memory  variables  or  arrays  into 
memory,  and  RELEASE  any  variables  you  no  longer  want.  Finally, 
SAVE  back  TO  the  memory  file.  The  SAVEd  file  will  reflect  your 
changes.  Use  this  technique  to  revise  memory  files  during  program 
development. 

-TIP-Programmers  often  use  memory  files  both  to  initialize  memory 
variables  at  the  beginning  of  the  program  and  to  reinitialize 
them  later.  You  can  create  several  memory  files  for  a  program  and 
RESTORE  FROM  them  as  needed.  You  can  then  RESTORE  the  original 
contents  of  certain  memory  variables  without  affecting 
others. -ENDBOX- 

-H2 -MACRO  SUBSTITUTION 

Macro  (S)  substitution  replaces  in  an  expression  the  name  of  a 
character  memory  variable  with  its  contents  Use  it  when  dBASE 
expects  a  lateral  value,  such  as  a  filename.  By  varying  the 
contents  of  che  memory  variable  that  the  macro  reads,  macro 
substitution  lets  you  use  one  command  to  send  a  variety  of 
instructions. 

The  most  common  use  of  macro  substitution  in  dBASE  programming  is 
with  the  USE  command: 

-M-@  . . .  SAY  "Enter  filename"  GET  filename-L- 
READ-L- 

USE  {.filename. -N- 

When  stringing  together  (concatenating)  macros,  separate  the  two 
elements  with  a  period: 

-M-@  ...  SAY  "Enter  drive  label  (e.g.,  B:)"  GET  drive-L- 

@  ...  SAY  "Enter  filename"  GET  filename-L- 

READ-L- 

USE  idrive. & filename. -N- 

You  can  also  combine  a  macro  with  a  literal  string: 
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-M-«  ...  SAY  "Enter  drive  where  you've  stored  Setup" ;~L~ 

GET  drive-L- 
USE  Sdrive.Setup-N- 

You  can  store  an  expression  to  a  memory  variable,  and  later  use 
the  variable  with  a  macro: 

-M-STORE  Lastname  to  m  field-L- 
STORE  "Smith"  TO  m  choTce-L- 
LOCATE  FOR  &m_fiel3.  =  Sm_choice.-N- 

You  can  even  build  an  expression  with  macro  substitution: 

-M-STORE  Lastname  to  m  field-L- 
STORE  "Smith"  TO  m_choice-L~ 

STORE  m_field  +  "  =  "  +  m  choice  TO  m  expr-L- 
LOCATE  FOR  &m_expr.-N~ 

-TIP-If  your  program  only  uses  expression  macros  such  as  USE 
ifilename. ,  and  not  command  macros,  include  the  command  SET 
EMACRO  ON  in  your  program  setup.  This  will  speed  up  the  execution 
time  of  your  program,  because  dBASE  IV  won't  call  in  the  full 
compiler  to  expand  the  macro . -ENDBOX- 

-C0MMEN1 -Special  cases  involving  macros 

~#~1.  In  RunTime,  you  cannot  begin  a  command  line  with  a  macro. 
For  example,  the  following  works  in  dBASE  but  not  in  RunTime: 

-M-mvar  =  "name"-L- 
imvar.  =  "Smith"-N- 

For  use  in  RunTime,  replace  the  last  lin%  with: 

-M-STOPE  "Smith"  TO  &mvar.-N~ 

-#-2 .  You  can  use  macro  substitution  in  a  DO  WHILE  condition  only 
if  the  value  of  the  variable  does  not  change  during  the  run  of 
the  loop.  This  is  because  dBASE  IV  evaluates  the  DO  WHILE 
condition  once  only,  at  the  beginning  of  the  loop.  After  that,  it 
executes  the  loop  from  memory. 

The  following  loop  runs  as  expected,  because  the  value  of  the 
variable  condition  doesn't  change  during  the  run  of  the  loop. 

-M-STORE  "Lastname  =*  ’Jones'"  TO  condition-L- 
DO  WHILE  scondition.  .AND.  .NOT.  EOF()-L- 
*  <commands>-L~ 

ENDDO-N- 

However,  in  the  following  example,  the  second  STORE  command 
changes  the  value  of  condition  to  .F..  Since  dBASE  parses  the  DO 
WHILE  command  only  once,  this  code  results  in  an  infinite  loop. 
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-M-STORE  "5  <  10"  TO  condition-L- 
DO  WHILE  icondition.-L- 

STORE  "20  <  10"  TO  condition. ~L~ 
ENDDO-N— ENDCOM- 
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-HI -DATABASE  SYSTEM  ARCHITECTURE 

As  a  house  rests  on  its  foundation,  a  dBASE  application  program 
is  supported  by  a  database  system.  A  database  system  is  a  set  of 
related  database  and  index  files.  Your  application  is  only  as 
good  as  the  database  system  beneath  it. 

Because  designing  and  building  a  database  system  is  not  pure 
programming,  many  programmers  tend  to  give  it  less  attention  than 
it  deserves.  This  early  phase  in  applications  design  is,  however, 
perhaps  the  most  important  part  of  the  entire  process.  At  this 
point,  you  identify  the  user's  needs  and  incorporate  them  into 
your  fundamental  design.  Careful  planning  here  minimizes  redesign 
effort  and  support  costs  later  on. 

-H2-WHAT  THIS  CHAPTER  COVERS 

This  chapter  discusses  the  design  of  the  database  system 
underlying  your  application  program.  It  covers: 

-o-Doing  a  needs  analysis 

-o-Three  rules  of  database  design 

-o-Designing  a  database  system- ENDLIST- 

-H2- DOING  A  NEEDS  ANALYSIS 

The  ultimate  purpose  of  an  application  program  is  to  manage 
information  in  a  manner  that  simplifies  day-to-day  operations  for 
the  end  user.  You  should  therefore  try  to  discover  and  clarify 
what  those  needs  are. 

This  section  recommends  some  basic  steps  for  determining  what 
your  application  should  do.  The  method  shown  here  assumes  that 
you  are  developing  an  application  for  a  company.  However,  whether 
you  are  an  independent  consultant,  a  systems  analyst  in  a 
corporate  MIS  department,  or  a  programmer  writing  applications 
for  your  own  use,  following  these  steps  will  help  ensure  the 
usefulness  of  your  application. 

-#-l.  Determine  the  overall  purpose  of  the  individuals  or 
organization  requesting  the  application. 

What  do  they  want  to  accomplish?  What  process  will  your 
application  automate?  Obtain  a  copy  of  the  procedure  manual,  if 
one  exists,  and  read  the  relevant  sections. 

-#-2 .  Identify  the  specific  tasks  involved  in  the  process. 


May  17,  1988 


Page  1 


Programming  with  dBASE  IV 


Ch.  4,  Sys.  Arch. 


Ask  staff  to  describe  what  they  do,  day-to-day,  on  the  job.  As 
they  describe  their  functions,  prompt  them  for  the  forms, 
reports,  memos,  and  letters  that  they  use  in  the  course  of  these 
activities. 

Also  ask  staff  to  describe  any  routine  communication  that  occurs 
during  an  operation.  Note  informal  phone  calls  and  conversations 
as  well  as  more  formalized  meetings  and  interactions.  Your 
application  might  be  able  to  save  staff  time  by  automating  some 
of  this  information  exchange. 

-#-3 .  Identify  any  improvements  to  the  process  that  staff  wish  to 
make. 

Encourage  staff  to  discuss  inefficiencies  in  the  current  work 
system.  Ask  them  for  any  improvements  they  have  in  mind,  such  as 
changes  to  forms  or  new  reports. 

- #-4 .  Chart  the  process  as  you  understand  it,  based  upon  your 
completion  of  steps  1-3. 

Draw  a  rough  flow  chart  depicting  the  process.  Indicate  when 
forms  are  completed  or  reports  are  produced,  who  receives  the 
copies  and  what  they  do  with  them,  and  what  information  is 
exchanged  on  the  phone,  in  meetings,  and  even  informally. 

-#-5.  Confirm  your  understanding  of  the  work  system  with  the 
staff. 

Present  your  flow  chart  to  the  staff.  Ask  them  to  point  out  any 
corrections  to  the  process,  and  make  relevant  changes. 

-#-6.  Streamline  the  process,  and  obtain  staff  confirmation  of 
your  proposed  changes. 

Scrutinize  the  process  that  you've  flow-charted  and  refine  it  as 
much  as  possible.  Look  for  duplication  among  forms  and 
procedures,  unused  reports,  and  unwieldy  work  systems.  For 
example,  one  developer  discovered  that  separate  departments  were 
each  cutting  and  pasting  a  standard  report  to  meet  their  needs. 

No  ona  was  using  the  report  in  its  original  forml -ENDLIST- 

-H2 -THREE  ROLES  OF  DATABASE  DESIGN 

Like  a  careful  needs  analysis,  proper  database  design  will 
benefit  you  in  the  long  run.  It  can  spare  you  considerable  time 
revi.--.ing  the  database  file  structure  later. 

Good  database  design  also  minimizes  the  amount  of  redundant  data 
in  the  database  system.  This  reduces  search  times  and  maintains  a 
higher  level  of  data  integrity  in  the  system. 
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Three  rules  of  proper  database  design  are  now  genera] ly 
accepted.  Apply  these  rules  in  order  when  designing  a  database 
file. 

-#~1.  First  normal  form:  Remove  repeating  fields  from  database 
files. 

In  the  database  file  structure  shown  in  Figure  4-1,  the  Part_id 
and  Part_name  fields  can  have  different  values  for  a  single 
vendor,  because  one  vendor  can  supply  a  variety  of  parts.  This 
makes  Vendor_id  and  Vendor  repeating  fields  (see  listing  in 
figure) . 

To  eliminate  the  repetition,  split  the  database  file  into  two 
files  as  shown  in  Figure  4-2.  Relate  the  files  on  Vendor_id  to 
produce  the  listing. 

-ILLUS-Figure  -l\mSingle  database  file  with  repeating 
f ields-EHDFIG- 

PARTS 

Vendor_id 

Vendor 

Part_id 

Part_name 

<more  fields> 


-ILLUS-Figure  4-2\mEliminating  repeating  fields  with  two  database 
f iles-ENDFIG- 


VENDORS 
Vendor_id  \ 

Vendor  \ 

Address l_v  \ 

Address2_v 
<more  fields> 


GOODS 
Part_id 
Part_name 
Date_order 
\  Vendor_id 
<more  fields> 


-#-2 .  Second  normal  form:  Dependent  fields  in  a  record  should 
depend  on  the  entire  key  expression. 


Figure  4-3  shows  a  hypothetical  database  file  called  Ord_cust, 
indexed  on  the  compound  key  Cust_id  +  PO_number .  Because  a  single 
customer  can  make  more  than  one  order,  data  about  the  customer  — 
such  as  the  customer  name,  address,  and  phone  number  —  depends 
upon  (that  is,  changes  with)  Cust_id  but  not  PO_number. 


This  condition  is  known  as  peurtlal  dependence.  Because  the  same 
customer  data  may  occur  for  different  orders,  the  user  has  to 
scan  the  entire  file  simply  to  change  data  about  that  customer. 
New  data  about  a  customer,  such  as  an  address,  must  be  added  for 
each  occurrence  of  the  customer  name. 
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The  solution,  once  again,  is  to  create  two  files  and  link  them  on 
a  common  field,  as  shown  in  Figure  4-4. 

-ILLUS-Figure  4-3\mDatabase  file  with  partial  dependence-ENDFIG- 


ORD  CUST 

Cust_id 

PO_number 

Customer 

Address_cl 

Address_c2 

Phone 

Date_trans 
<more  fields> 


-ILLUS-Figure  4-4\mDatabase  files  with  full  dependence-ENDFIG- 


CUST 

Cust_id  - 

Customer 

Addressl_c 

Address2_c 

Phone 

<more  fields> 


Cust_id 

PO_number 

Part_qty 

Part_id 

Date_trans 

<more  fields> 


-#-3.  Third  normal  form:  Dependent  fields  should  depend  only  upon 
the  key  expression,  not  upon  non-key  fields. 

Figure  4-5  shows  a  hypothetical  database  file,  Part_ord,  which  is 
indexed  on  the  compounc,  key  Cust_id  +  PO_number .  It  contains 
information  on  both  parts  and  orders.  In  this  structure  data 
about  a  part  (its  name,  description,  cost,  and  so  on)  depends 
upon  the  non-key  field  Part_id  rather  than  the  key  expression. 

This  condition  is  known  as  tremsitive  dependence.  Because  many 
customers  can  order  the  same  part,  the  same  parts  data  will 
repeat  throughout  the  database  file.  This  makes  changing  the  data 
difficult,  just  as  it  was  in  the  case  of  partial  dependence. 

Correct  the  problem  by  splitting  Part_ord  into  two  files  (see 
Figure  4-6) . 

-ILLUS-Figure  4-5\mDatabase  file  with  transitive 
dependence- ENDFIG- 


PART  ORD 

Cust_id 

PO_number 

Part_id 

Part_name 

Descript 

Cost 
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<more  fields> 


ILLUS-Figure  4-6\mDatabase  files 
CUST 

Part_id  \ 

Part_name  \ 

Date_order 
Vendor_id 
<more  fields> 


with  correct  dependence-ENDFIG' 

ORDERS 
Cust_id 
PO_number 
\  Part_id 
Part_qty 
Date_trans 
<more  fields> 


-H2- DESIGNING  A  DATABASE  SYSTEM 


Once  you  have  done  a  thorough  needs  analysis  and  have  reviewed 
the  rules  of  proper  database  design  (see  previous  two  sections) , 
you  are  ready  to  start  designing  the  database  system  for  your 
application.  This  section  outlines  the  basic  steps  to  follow. 

-#-l.  Using  the  materials  that  you., .gathered  and  the  flow  chart 
you  drew,  list  the 'items  of  information  that  the  system  needs  to 
collect  and  produce. 

-#-2.  Assign  each  item  a  legal  dBASE  field  name  and,  optionally, 
alphabetize  the  list.  You  have  now  created  your  field  list. 

-#-3.  Create  a  table  showing  the  fields  occurring  in  the 
different  forms  and  reports.  Table  4-1  shows  the  distribution  of 
fields  for  the  Goods  and  Orders  database  files.  Note  the  three 
calculated  fields,  which  come  from  neither  f ile. -ENDLIST- 


-TABLE-Table  4-l\mDistribution  of  fields  in  Goods  and  Orders 


1 

|  — — - 

1 

I-- 

Input  Form — | 

calc.  | - 

-Output  Report - 

field 

Field  Inventory  Orders 

Inventory 

Inventory 

Orders 

Orde 

Listing 

Cost 

Listing 

Prof 

Part  id 

X 

X 

X 

X 

Date  order 

X 

X 

Part  name 

X 

X 

X 

X 

Descript 

X 

X 

Lead  time 

X 

X 

Price 

X 

X 

X 

Qty  2order 

X 

X 

Qty  onhand 

X 

X 

X 

Vendor  id 

X 

X 

X 

X 

Discontinu 

X 

X 

X 

Cost 

X 

X 

X 

X 

Comment 

X 

X 

May  17,  1988 

Page  5 

Programming  with  dBASE  IV 


Ch.  4,  Sys.  Arch 


Tot_cost 

Prof it_mgn 

Cust_id 

PO_number 

Part_id 

Date_trans 

Part_qty 

Notes 

Emp_id 

Invoiced 

Profit  sis 


x 

X 

X 

x 

x 

x 

x 

X 


X 

x 


x 


X 

X 


X 

X 

X 

X 

X 

X 

X 

X 


-ENDTABLE- 

~#~4.  Prepare  a  system  tiles  and  fields  list  as  shown  in  Figure 
4-7.  Using  a  table  like  the  one  created  in  step  3  (the  actual 
table  would  list  all  fields  in  the  database  system) ,  decide  the 
database  files  you  want  to  use  in  the  system,  and  what  fields  go 
in  each  file.  Assign  each  file  a  legal  dBASE  name.  Be  sure  to 
follow  the  three  rules  of  database  design  listed  in  the  previous 
section.  You  have  now  created  yiur  data  dictionary. 

-#-5.  Indicate  the  needed  index  key  expressions  on  the  system 
files  and  fields  list  (see  Figure  4-7) .  These  include: 

-oo-Search  ( primary )  keys  for  conducting  rapid  searches 

-oo-Relational  ( foreign )  keys  for  relating  files 

-oo-Input  keys  to  order  data  entry  forms 

-oo-Output  keys  to  order  reports  and  listings-ENDLIST- 

-#~6.  Identify  any  relations  between  files  by  drawing  a  line 
between  the  two  key  fields  (see  Figure  4-7) . 

-ILLUS-Figure  4-7\mSystem  files  and  fields  list-ENDFIG- 


Now  you  can  build  the  database  system  with  confidence.  Use 
CREATE/MODIFY  STRUCTURE  to  create  the  database  files  (see  Chapter 
6,  "Designing  Databases,"  in  Using  the  Menu  System).  Use  the 
INDEX  and  SET  RELATION  commands  to  index  and  relate  the  database 
files  (see  Chapters  11  and  13  in  this  book  and  Chapters  2  and  3 
in  Language  Reference) . 

Test  the  system  using  dummy  data  (a  copy  of  real  data  from  a 
prior  system) .  Compare  the  results  obtained  with  results  from  the 
previous  system.  Also,  in  the  reports  generator  use  the  Quick 
Layout  option  of  the  Layout  menu  to  generate  a  quick  report.  When 


May  17,  1988 


Page  6 


Ch.  4,  Sys.  Arch. 


Programming  with  dBASE  IV 


you're  satisfied  that  the  structure  is  correct  and  that  you  have 
included  the  needed  index  tags  and  relations,  LIST  STRUCTURE  TO 
PRINT  and  file  the  output  in  your  documentation  binder. 


1.  E.F.  Codd,  "A  Relational  Model  of  Data  for  Large  Shared  Data 
Banks,"  Communications  of  the  Association  of  Computing  Machinery 
13  (June  6,  1970),  377-387. 
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VENDORS  GOODS  ORDERS 


CUST 

Cu«t_td 

Cuatomr 

Addrmsi.c 

AddrmsZ.e 
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The  main  module  of  a  program  controls  the  program  as  a  whole,  it 
establishes  the  working  environment  and  initializes  global  memory 
variables  used  throughout  the  program.  It  also  displays  the  main 
menu  and  calls  the  subprograms  activated  by  it. 

-TI?-Write  a  boilerplate  (standard)  main  program  that  includes 
the  commands  you  use  regularly.  Then  copy  it  whenever  you  begin  a 
new  programming  pro j ect . -ENDBOX- 

-H2-WHAT  THIS  CHAPTER  COVERS 

This  chapter  discusses  the  main  program  modules  of  the  Business 
sample  application.  It  covers  the  following  topics: 

-o-The  program  preamble 

-o-Setting  up  the  working  environment 

-o-Initializing  memory  variables 

-o-Displaying  the  main  menu 

-o-Opening  and  relating  files 

-o-Cleaning  up  the  environment-ENDLIST- 

-H2-THE  PROGRAM  PREAMBLE 


Every  program  should  start  with  a  pro gram  header  or  preamble  that 
includes  the  program  name,  the  programmer's  name,  what  the 
program  does,  and  an  edit  history.  There  is  no  mandatory  format 
for  the  program  preamble.  Here  is  the  preamble  to  the  Business 
application: 


♦PROGRAM  NAME: 
* 

* 

♦LAST  CHANGED: 
♦WRITTEN  BY: 


Business . prg-L- 
MAIN  MENU 

Sample  dBASE  Accounting  System 
4/27/88  1:13  P.M. 

Bob  Newman- L- 


-H2-SETTING  UP  THE  WORKING  ENVIRONMENT 

The  working  environment  of  a  program  includes  the  default 
configuration  of  the  screen,  printer,  and  keyboard,  and  other 
aspects  of  the  environment  in  which  your  program  runs.  Using 
primarily  SET  commands  and  system  memory  variables,  you  can 
establish  a  default  working  environment  for  vour  program.  In  the 
program  setup  area,  define  only  environmental  characteristics 
that  will  remain  constant  throughout  your  application. 

Table  6-1  lists  SET  commands  that  are  commonly  used  in  program 
setup  code.  For  ON/OFF  SET  commands,  the  table  shows  the  setting 
recommended  for  use  in  programs.  (See  Chapter  3  of  Language 
Reference  for  more  information  on  the  SET  commands.) 


-TABLE-Tabl e  6-l\mSET  commands  commonly  used  in  program  setup 
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Operation 

Configure  the  screen  display 
Specify  a  type  of  monitor 
Set  default  colors 

Define  a  default  border 
Configure  the  clock1 
Prevent  access  to  design  mode2 3 


SET  Command 


SET  DISPLAY  TO 
SET  COLOR  TO, 

SET  COLOR  OF  ...  TO  ... 

SET  BORDER  TO 
SET  CLOCK  ON,  SET  CLOCK  TO 
SET  DESIGN  OFF 


Configure  screen  messages 
Suppress  the  status  bar2 
Suppress  sytem  messages  that 

show  on  row  0  when  STATUS  is  OFF2 
Suppress  navigation  line  in 
full-screen  menus 
Suppress  system  help  messages 
Suppress  system  information  boxes 
Suppress  system  safety  messages4 
Suppress  system  responses  to 
certain  commands 

Suppress  display  of  command  lines 


SET 

SET 

SET 

SET 

SET 

SET 

SET 

SET 


STATUS  OFF 
SCOREBOARD  OFF 

MENUS  OFF 

HELP  OFF 
INSTRUCT  OFF 
SAFETY  OFF 
TALK  OFF 

ECHO  OFF 


Configure  data  handling  and  display 


Specify  the  number  of  decimals  SET 
Allow  inexact  comparisons  SET 
Ignore  DELETEd  records  SET 
Show  column  headings  SET 


Insert  spaces  between  expressions  SET 


defined  with  ?/?? 

Doesn't  stop  search  at  near  miss  SET 

Configure  the  keyboard 
Configure  function  keys  SET 

Keep  -ESC-  from  interrupting  the  SET 

program 

Control  the  keyboard  buffer  SET 

Configure  drives  and  directories 
Set  the  default  drive  SET 

Set  the  file  search  path  SET 

Configure  the  bell 

Define  pitch  and  duration  SET 

Suppress  the  system  bell  SET 


DECIMALS  TO 
EXACT  OFF 
DELETED  ON 
HEADING  ON 
SPACE  ON 

NEAR  OFF 


FUNCTION  ...  TO 
ESCAPE  OFF 

TYPEAHEAD  TO 


DEFAULT  TO 
PATH  TO 


BELL  TO 
BELL  OFF 


1.  The  system  clock  is  off  by  default,  except  in  the  full-screen 
commands,  where  it  is  permanently  on.  The  default  clock  location 
is  the  upper  right  corner  of  the  screen. 

2.  SET  DESIGN  OFF  if  your  application  interface  uses  full-screen 
commands  such  as  BROWSE  and  EDIT.  This  prevents  users  from 
altering  the  design  of  screen  objects. 

3.  SET  STATUS  OFF  and  SET  SCOREBOARD  OFF  in  your  program,  so  that 
you  can  display  your  own  messages  at  the  top  and  bottom  of  the 

screen. 
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4.  With  SAFETY  OFF,  dBASE  IV  does  not  warn  the  user  before 
overwriting  files  of  the  same  name.  The  Business  application  SETs 
SAFETY  OFF  so  that  users  won't  see  an  overwrite  warning  when  the 
application  indexes  a  database  file.-ENDTABLE- 

Table  6-2  lists  some  system  memory  variables  for  the  program 
setup  area,  showing  suggested  settings  where  practical.  The 
system  variables  shown  here  control  print  settings  that  are 
likely  to  remain  constant  throughout  a  program.  See  Chapters  14 
and  15  of  this  book  and  Chapter  5  of  Language  Reference  for  more 
information  on  the  dBASE  IV  system  memory  variables. 

-TABLE-Table  6— 2\mSystem  memory  variables  used  in  program 
setup1 


Operation 

Specify  a  printer  driver  file 
Specify  a  print  form  file 
Set  printer  pitch 
Set  printer  to  letter  quality 
Define  starting  print  code 
Define  ending  print  code 
Do  a  form  feed  before  PRINTJOB 
. . . ENDPRINTJOB 
Print  defined  boxes 
_ -ENDTABLE- 


System  memory  variable 

_pdriver  =  l,<filename>" 
_pform  =  "<f ilename>" 
_ppitch  =  "<pitch>" 
_pquality  =  .T. 

_pscode  =■  "<start  code>" 
_pecode  =  "<end  code>" 
_pe j ect  -  "BEFORE" 

box  =»  .T. 


Here  is  the  program  setup  code  from  the  main  program  of  the 
Business  application. 

The  CLEAR  ALL  command  closes  all  database  files,  releases  all 
memory  variables,  and  selects  work  area  1.  This  is  a  safety 
precaution  in  case  someone  has  been  working  with  dBASE  IV  before 
the  user  runs  your  application. 

The  SET  commands  set  up  the  program  environment. 

The  SET  FUNCTION  command  defines  the  -F2-  key  to  enter  the  DOS 

DIR  command.  (You  can  program  -F2-  through  -F10-,  -SHIFT - Fl- 

through  -SHIFT - F9-,  and  -CONTROL - FI-  through  -CONTROL - F10-. 

A  semicolon  (;)  at  the  end  of  a  function  key  definition  executes 
the  command  assigned  to  the  key  when  the  key  is  pressed.) 

Remember  to  reset  function  keys  to  their  default  assignments 
before  ending  the  program.  The  discussion  of  SET  FUNCTION  in 
Chapter  3  of  Language  Reference  lists  these  default  settings. 

The  Wambell  procedure  defines  a  simple  melody  to  serve  as  a 
warning  bell.  After  sounding  the  bell,  the  routine  resets  the 
default  pitch  and  duration.  The  Business  application  issues  a  DO 
Warn_bell  with  each  warning  message. 

-NOTE-The  actual  setup  code  for  this  application  also  includes  a 
routine  that  defines  display  colors  for  color  and  monochrome 
monitors.  The  section  "Working  with  Colors"  in  Chapter  7  shows 
the  routine  and  discusses  how  to  control  screen  color  in  dBASE  IV 
programs . -ENDBOX- 
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-M-CLEAR  ALL-L¬ 
ON  KEY  FI  DO  Helper-L- 
SET  BELL  OFF-L- 
SET  DELETED  ON-L- 
SET  ESCAPE  OFF-L- 
SET  EXACT  OFF-L- 

SET  FUNCTION  F2  TO  "RUN  DIR;"-L~ 

SET  HEADING  ON-L- 

SET  HELP  OFF-L- 

SET  NEAR  OFF-L- 

SET  SAFETY  OFF-L- 

SET  SCOREBOARD  OFF-L- 

SET  STATUS  OFF-L- 

SET  TALK  OFF-L- 

\m-L- 

\m-L- 

PROCEDURE  Warn_bell-L- 
SET  BELL  TO  880, 4-L- 
??  CHR(7) -L- 
SET  BELL  TO  1400, 4-L- 
??  CHR(7)-L~ 

SET  BELL  TO  880, 4-L- 
??  CHR(7) -L- 
SET  BELL  TO-N- 


-TlP-If  your  application  will  be  used  with  a  partitioned  hard 
disk  drive,  you  can  put  the  system  files  on  drive  C  and  the  data 
on  drive  D.  In  that  case: 

-M-SET  DEFAULT  TO  D-L- 

SET  PATH  TO  D:\data-N-ENDBOX~ 

-H2- INITIALI Z ING  MEMORY  VARIABLES 

After  setting  up  the  working  environment,  the  main  program 
initializes  the  memory  variables  that  the  program  will  use.  Here 
is  the  code  that  initializes  the  global  memory  variables  used 
throughout  the  Business  application.  (Chapter  3  provider  an 
overview  of  how  memory  variables  work  in  dBASE  IV.) 

-M-STORE  .F.  TO  erased,  not_valid-L- 
STORE  "  "  TO  choice,  answer-L- 
record_nui  =•  0-N- 

The  following  code  initializes  memory  variables  local  to 
Orders. prg.  Similar  code  can  be  found  in  the  other  subprograms  of 
the  Business  application.  Note  that  the  four  lines  define 
character,  numeric,  date,  and  logical  variables,  respectively. 

-M-STORE  "  "  TO  cust_id,  emp_id,  part_id,  po_number~L~ 
part_qty  =■  0-L- 
date_trans  =  {  /  /  )-L~ 

invoiced  =  .F.-N- 

-H2-DISPLAYING  THE  MAIN  MENU 
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Most  dBASE  programs  have  one  main  menu  from  which  all  submenus 
branch.  This  allows  just  one  entry  and  one  exit  from  the  program. 
The  main  menu  displays  whenever  control  returns  to  the  main 
program. 

Here  is  partial  code  for  the  main  menu  of  the  Business 
application.  See  Chapter  8  for  the  complete  routine  and  more 
information  on  the  dBASE  IV  menu-building  capabilities. 


-MPROCEDURE  Def_menu-L- 

DEFINE  POPUP  main_mnu  FROM  1,24  TO  20,56;-L- 

MESSAGE  "Please  choose  a  database  file  or  utility"-!,- 


DEFINE 

BAR 

2 

OF 

main 

mnu 

PROMPT 

•i 

A-T 

FURNITURE  INDUSTRIES"  SKIP- 

DEFINE 

BAR 

3 

OF 

main 

mnu 

PROMPT 

ii 

MAIN  MENU"  SKIP-L- 

DEFINE 

BAR 

4 

OF 

main 

mnu 

PROMPT 

it 

====================== "  SKIP 

DEFINE 

BAR 

6 

OF 

main 

mnu 

PROMPT 

ii 

Databases:"  SKIP-L- 

DEFINE 

BAR 

7 

OF 

main 

mnu 

PROMPT 

n 

1. 

EMPLOYEES "-L- 

DEFINE 

BAR 

8 

OF 

main 

mnu 

PROMPT 

n 

2. 

CUSTOMERS "-L- 

DEFINE 

BAR 

9 

OF 

main 

mnu 

PROMPT 

ii 

3. 

VENDORS "-L- 

DEFINE 

BAR 

10 

OF 

main 

mnu 

PROMPT 

n 

4. 

FURNITURE  INVENTORY "-L- 

DEFINE 

BAR 

ii 

OF 

main 

mnu 

PROMPT 

ii 

5. 

ORDER  TRANSACTIONS "-L- 

DEFINE 

BAR 

12 

OF 

main 

mnu 

PROMPT 

ii 

6. 

ACCT  RECEIVABLE" -L- 

DEFINE 

BAR 

14 

OF 

main 

mnu 

PROMPT 

ii 

Utilities:"  SKIP-L- 

DEFINE 

BAR 

15 

OF 

main 

mnu 

PROMPT 

n 

R. 

REPORTS "-L- 

DEFINE 

BAR 

16 

OF 

main 

mnu 

PROMPT 

ii 

B. 

.  BACK/RESTORE  DATA"-L- 

DEFINE 

BAR 

17 

OF 

main_ 

_mnu 

PROMPT 

n 

Q. 

.  QUIT"-L- 

RETURN-N- 

-H2 -OPENING  AND  RELATING  FILES 

The  Business  application  program  contains  six  separate  programs. 
Each  of  them  uses  its  own  database  files,  indexes,  and  screen 
format  files.  Consequently,  this  main  Business  program  does  not 
open  any  files.  Instead,  the  subprograms  open  files  as  needed. 

The  following  code  from  Orders  opens  and  relates  the  Orders, 
Goods,  Cust,  and  Employee  database  files  with  their  respective 
index  files.  Comparable  routines  can  be  found  in  Employee,  Cust, 
Vendors,  Goods,  and  Acct_rec. 

The  ORDER  clauses  open  the  named  index  tags,  while  the  IN  clauses 
indicate  a  different  work  area  for  each  set  of  files.  The  SET 
RELATION  command  relates  Orders  to  each  of  the  other  three 
database  files.  The  GO  TOP  synchronizes  the  related  files. 
(Chapters  11  and  13  discuss  indexing  and  relating  database  files, 
respectively. ) 

-M-SELECT  1-L- 

USE  Orders  ORDER  Order-L- 

USE  Goods  ORDER  Part_id  IN  2-L- 

USE  Cust  ORDER  Cust_id  IN  3-L- 

USE  Employee  ORDER  Emp_id  IN  4-L- 

SET  RELATION  TO  Part_id  INTO  Goods,  Cust_id  INTO  Cust,  ;-L~ 
Emp_id  INTO  Employee-L- 
GO  TOP-N- 


May  17,  1988 


Page  5 


Programming  with  dBASE  IV 


Chi  6,  Main  Program 

-TIP-In  a  high-level  program,  open  only  files  that  you  intend  to 
use  throughout  the  application.  Keep  as  few  files  as  possible 
open  at  once  to  minimize  the  risk  of  catastrophic  data  loss.  A 
rule  of  thumb  is  to  open  files  only  when  you  need  them,  and  close 
them  as  soon  as  you  are  finished  with  them.  If  you  must  leave 
database  files  open  in  your  application,  SET  AUTOSAVE  ON.-ENDBOX- 

-H2- CLEANING  UP  THE  ENVIRONMENT 

Just  as  a  house  painter  shouldn't  leave  behind  rollers  and  drip 
pans,  your  application  shouldn't  leave  behind  open  files  and 
altered  environmental  settings. 

To  properly  clean  up  the  environment  that  you  established 
earlier,  close  all  open  database  files,  release  memory  variables, 
restore  the  working  environment  to  its  original  settings,  and 
return  users  to  the  point  from  which  they  entered  the  program. 

The  following  routine  occurs  at  the  end  of  Vendors,  Orders,  and 
the  other  subprograms  in  the  Business  application.  The  RETURN  TO 
MASTER  command  releases  all  PRIVATE  memory  variables  in  the 
sub-program.  No  commands  are  needed  to  restore  the  working 
environment,  because  the  application  issues  a  QUIT  command  when 
the  user  exits  the  application.  The  QUIT  command  automatically 
restores  tne  working  environment  to  its  default  values. 

-M-CLOSE  rATABASKS-L- 
CLEAR  WINCOWS-r,- 
RETURN  TO  MASTER-N- 
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-Hl-THE  LOOK  OF  YOUR  APPLICATION 


You  can  improve  the  look  of  your  application  using  the  techniques 
discussed  in  this  chapter.  Appropriately  placed  lines,  boxes, 
windows,  and  color  make  data  entry  and  menu  screens  easier  to 
read,  and  give  the  entire  application  a  more  polished  look. 

-H2-WHAT  THIS  CHAPTER  COVERS 

This  chapter  shows  you  how  to  enhance  screen  forms  and  menus  with 
lines,  boxes,  windows,  borders,  and  color.  The  topics  it  covers 
are: 

-o-Displaying  lines  and  boxes 
-o-Working  with  windows 
-o-Working  with  borders 
-o-Working  with  colors-ENDLIST- 

This  chapter  focuses  on  the  screen  environment,  and  therefore 
does  not  discuss  how  to  print  lines  and  boxes.  For  more 
information  on  printing  lines  and  boxes,  see  Chapter  15  of  this 
book.  Chapter  1  of  Using  the  dBASE  IV  Applications  Generator 
discusses  interface  design  principles. 

-H2-S0ME  TERMINOLOGY 

Before  reading  this  chapter,  you  should  be  clear  about  the 
difference  between  a  box  and  a  window.  Boxes  are  rectangles  that 
you  draw  on  the  screen,  usually  surrounding  related  items  in  a 
screen  form.  Unlike  windows,  boxes  are  just  character's  on  the 
screen.  If  text  exceeds  the  perimeter  of  the  box,  it  overwrites 
the  border  (see  Figure  7-1) . 

-SCREEN-Figure  7-l\mString  exceeding  box  dimensions-ENDFIG- 


Windows,  on  the  other  hand,  are  rectangular  areas  of  the  screen 
in  which  program  operations  occur.  You  use  windows  to  LIST  output 
or  display  memo  fields,  prompts,  and  messages.  Text  that  exceeds 
the  window  dimensions  wraps  or  scrolls  within  the  window  (see 
Figure  7-2) . 

-SCREEN-Figure  7-2\mStrinq  exceeding  window  dimensions-ENDFIG- 

) 

-H2-  DRAWING  AND  CLEARING  LINES  AND  BOXES 


May  17,  1988 


page  1 


Programming  with  dBASE  IV 


Ch.  7,  Look  of  App 


You  can  code  lines  or  boxes  like  those  shown  in  Figure  7-3  with 
the  dBASE  IV  @...T0  command.  This  command  lets  you  position  the 
line  or  box  on  the  screen  and  define  a  variety  of  possible 
borders.  The  examples  in  this  section  are  all  based  upon  the 
screen  form  design  shown  in  the  figure.  Chapter  9  discusses 
screen  forms  in  detail.  "Working  with  Colors"  in  this  chapter 
explains  how  to  color  objects  on  the  screen. 


-SCREEN-Figure  7-3\mVendor  screen  form-ENDFIG- 


-H3- Drawing  Lines  on  the  Screen 

You  can  draw  lines  in  screen  forms  to  visually  separate  entry 
fields  for  the  user.  The  command  that  draws  the  horizontal  line 
above  the  bottom  half  of  the  form  in  Figure  7-3  is: 

-M-@  14,5  TO  14,52  COLOR  R/W-N- 

Note  that  horizontal  line  definitions  have  the  same  beginning  and 
ending  row  coordinates.  To  draw  a  vertical  line  on  the  screen, 
keep  the  column  coordinates  the  same. 

To  make  the  horizontal  line  a  double  line,  you  would  use  the 
DOUBLE  option  of  the  @...T0  command: 

~M~@  14,5  TO  14,52  COLOR  R/W  DOUBLE-N- 

To  draw  lines  with  a  graphic  character  of  your  choice,  include 
the  character  with  the  J...TO  command.  Here's  how  to  draw  a 
20-character  line,  centered  on  the  screen,  with  the  graphic 
character  [ .  To  type  the  character,  hold  down  -ALT-  while  you 
type  the  number  219  on  the  numeric  keypad. 

-M~@  14,24  TO  14,43  "["-N- 

-H3-Drawing  Boxes  on  the  Screen 

Use  the  S...TO  command  to  position  boxes  on  the  screen,  specify 
their  dimensions,  and  define  their  border  characters.  The 
following  code  draws  the  double-lined  boxes  around  the  form  title 
and  the  vendor  number  prompt  in  Figure  7-3  above: 

-M-@  1,22  TO  3,53  COLOR  B/W  DOUBLE-L- 
@  5,4  TO  7,27  COLOR  R/W  DOUBLE-N- 

The  SET  BORDER  TO  command  also  affects  the  border  string  of  both 
lines  and  boxes. 

-NOTE-Use  the  DEFINE  BOX  command  to  print  lines  and  boxes  (see 
Chapter  14) .-ENDBOX- 

-H3-Clearing  Lines  and  Boxes 
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The  @... CLEAR  TO  command  lets  you  clear  lines  and  boxes  from  the 
screen.  Just  provide  the  same  coordinates  you  did  when  you  drew 
the  lines  and  boxes.  The  following  example  displays  a  prompt  in  a 
box.  Then  it  CLEARS  the  area  within  the  box  and  displays  a  second 
prompt : 

-M-@  10,10  CLEAR  TO  14,60-L- 
@  10,10  TO  14,60-L- 

@  11,11  SAY  "Please  enter  a  vendor  no.  to  find:"  GET  m->vendor  id 

READ-L- 

-L- 

@9,11  CLEAR  TO  13 , 59-L- 

@  11,11  SAY  "Please  enter  a  part  no.  to  find:"  GET  m->part  id-L- 
READ-N- 

-H2 -WORKING  WITH  WINDOWS 

Windows  define  the  area  of  the  screen  where  operations  take 
place.  While  a  window  is  active,  all  screen  input  and  output 
occurs  within  it  (except  the  dot  prompt) .  The  system  treats  the 
top  left  position  in  the  window  as  coordinate  0,0  and  adjusts  any 
screen  coordinate  you  specify  accordingly. 

Figure  7-4  shows  a  data  LISTing  in  a  window. 

-SCREEN-Figure  7-4\mLISTing  to  a  window- ENDFIG- 


The  next  two  code  examples  refer  to  this  window.  See  "More  Uses 
of  Windows"  for  other  examples  of  how  to  use  windows  in  your 
applications. 

-H3-Defining  a  Window  and  Its  Borders 

To  DEFINE  a  WINDOW,  give  it  a  name  (limited  to  10  characters) , 
provide  screen  coordinates,  and,  optionally,  define  its  border 
and  colors.  You  can  define  up  to  20  windows. 

The  window  shown  in  Figure  7-4  is  defined  as  follows  ("Working 
with  Color"  shows  the  contents  of  c_list) : 

-M-DEFINE  WINDOW  list  FROM  5,5  TO  20,70  COLOR  &c_list-N~ 

You  can  also  make  the  border  a  double  line,  an  inverse  video 
panel,  or  a  character  string  of  your  choice.  See  DEFINE  WINDOW 
and  SET  BORDER  in  Language  Reference  for  more  details. 

-H3-Activating  and  Deactivating  Windows 


May  17,  1988 


page  3 


Programming  with  dBASE  IV 


Ch.  7,  Look  of  App. 


Once  you've  defined  one  or  more  windows,  ACTIVATE  and  DEACTIVATE 
them  to  control  when  they  appear  on  the  screen.  When  you  activate 
a  WINDOW,  it  covers  any  text  that  already  appears  on  the  same 
area  of  the  screen.  When  you  DEACTIVATE  the  WINDOW,  the  text 
reappears. 

Here's  the  complete  code  for  the  LISTing  shown  in  Figure  7-4 
above : 

-M-PROCEDURE  List_rec-L~ 

ACTIVATE  WINDOW  list-L- 
answer  =  "  "-L- 
CLEAR-L- 

- LIST  records - 

SCAN  WHILE  .NOT.  answer  $  "rR"-L- 
@0,0  SAY  ;-L- 

LIST  OFF  NEXT  10  Vendor_id,  Vendor,  Phone_vend~L~ 

WAIT  "Spacebar  to  continue  or  R  to  return  to  Option  Menu1 
TO  answer- L- 
CLEAR-L- 
ENDSCAN-L- 

DEACTIVATE  WINDOW  list-L- 
RETURN-N- 

dBASE  IV  defines  the  active  window  as  the  most  recently  ACTIVATEd 
one.  Consequently,  if  there  are  two  windows  on  the  screen  and  you 
DEACTIVATE  the  active  one,  the  remaining  window  is  ACTIVATEd 
automatically.  If  two  or  more  windows  remain,  the  most  recently 
ACTIVATEd  one  becomes  the  new  active  window. 

When  you  DEACTIVATE  a  WINDOW,  the  window  disappears  from  the 
screen  but  not  from  memory.  The  "Managing  Windows"  section 
explains  how  to  erase  window  definitions  from  memory. 

-H3-Moving  a  Window 

The  MOVE  WINDOW  command  lets  you  move  either  an  active  or  an 
inactive  window.  You  don't  need  to  supply  the  name  of  the  window 
you're  moving  if  it's  active. 

You  can  MOVE  a  WINDOW  in  two  ways.  First,  you  can  MOVE  the  WINDOW 
TO  new  screen  coordinates.  (You  only  have  to  supply  the  upper 
left  coordinates,  since  the  size  of  the  window  remains  as 
DEFINEd.)  Second,  you  can  MOVE  the  WINDOW  BY  rows  and  columns. 

The  following  code  MOVES  the  active  alert  WINDOW  five  rows  down 
and  five  columns  across  the  screen.  Then  it  activates  the  list 
window  to  display  a  list  of  vendors.  (Find_rec  is  a  procedure 
that  SEEKS  vendor  identification  codes  entered  by  the  user  in  the 
alert  window.) 

-M-DO  Find_rec-L~ 

IF  .NOT.  FOUND  ()-L- 
MOVE  WINDOW  BY  5,5-L- 
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ACTIVATE  WINDOW  list-L- 

@1,1  SAY  "Here  is  a  list  of  vendors:  "-L- 
DO  list_rec-L~ 

DEACTIVATE  WINDOW  alert-L- 
ENDIF-N- 

Once  you've  MOVEd  a  WINDOW,  dBASE  IV  updates  the  window 
definition  with  the  new  screen  coordinates.  Therefore,  the  next 
time  you  ACTIVATE  that  WINDOW,  it  will  appear  at  the  new  screen 
location. 

-H3~Managing  Window  Definitions 

If  you  plan  to  use  a  set  of  window  definitions  in  several 
applications,  SAVE  them  to  a  disk  file.  dBASE  IV  attaches  a 
default  .win  extension  to  the  window  definitions  filename. 

-M-SAVE  WINDOW  alert,  list  TO  Win_defs-N- 

To  save  all  windows,  SAVE  WINDOW  ALL  TO  Wlnjlels.  You  can  then 
RESTORE  the  definitions  when  you  want  to  use  the  windows  in  a 
program.  The  window  that  was  active  when  you  SAVEd  the 
definitions  will  again  be  active.  You  can  restore  specified 
windows,  or  all  windows  in  the  file  using  ALL. 

-M-RESTORE  WINDOW  alert,  list  FROM  Win_defs~N~ 

If  you  have  SAVEd  your  window  definitions  to  a  file,  you  can 
CLEAR  or  RELEASE  them  during  your  application  without  losing  the 
definitions.  This  allows  you  to  increase  the  amount  of  available 
memory.  Use  CLEAR  WINDOWS  to  erase  all  windows  from  the  screen 
and  remove  their  definitions  from  memory.  Use  RELEASE  WINDOWS  to 
erase  specified  windows  from  the  screen  and  remove  their 
definitions  from  memory: 

-M-RE LEASE  WINDOWS  alert,  list-N- 

-H3~More  Uses  of  Windows 

In  addition  to  the  LIST  window  shown  above,  there  are  many  other 
ways  to  use  windows  in  application  programs.  This  section 
discusses  five  other  popular  window  arrangements: 

-o-Top  and  bottom  windows  to  display  additional  data 

-o-A  vertical  look-up  window  to  get  information  from  a  related 
file 

-o-A  memo  field  in  a  window 

-o-Dialog  boxes  containing  error  messages  or  information 
prompts-ENDLIST- 
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The  section  "Providing  Context-Sensitive  Help"  in  Chapter  9  shows 
how  to  code  a  help  window. 

-H4-Top  and  bottom  report  windows 


You  can  stack  two  windows,  one  on  top  of  the  other,  to  display 
report  column  totals  on  the  same  screen  with  report  column 
headings  (see  Figure  7-5).  This  format  is  useful  where  the  report 
output  occupies  more  than  one  screen,  since  the  column  headings 
would  normally  scroll  out  of  view  by  the  time  the  totals  are 
visible. 


-SCREEN-Figure  7-5\mTop  and  bottom  report  windows-ENDFIG- 


-H4-A  look-up  window 

You  can  provide  a  look-up  window  to  display  information  that  is 
not  in  the  main  database  file.  This  lets  users  access  additional 
data,  such  as  employee  names,  department  codes,  or  part  numbers. 
Figure  7-6  shows  a  part  number  look-up  window. 

-SCREEN-Figure  7-6\mA  look-up  window- ENDFIG- 


The  code  for  this  example  is  in  Chapter  9  in  the  "Checking 
Against  a  Database  File"  section.  The  previous  example  in  that 
chapter,  in  the  "Checking  Against  a  List"  section,  also  uses  a 
look-up  window. 

-H4-A  memo  window 

You  can  display  in  a  window  the  contents  of  a  memo  field,  for 
users  to  read  or  edit  (see  Figure  7-7). 

-SCREEN-Figure  7-7\mA  memo  window- ENDFIG- 

The  following  lines  of  code  open  the  window  shown  when  the  user 

presses  -CTRL - HOME-  and  display  the  Notes  memo  field  in  the 

window.  When  the  user  presses  -CTRL END-,  the  window  closes  anc 

any  changes  are  saved.  This  code  fragment  would  normally  be  part 
of  a  screen  format  file  (see  Chapter  9) . 

-M-DEFINE  WINDOW  Memowindo  FROM  15,10  TO  20,70-L- 
@  17,  4  SAY  "NOTES:  "  GET  Notes  WINDOW  memowindo-N- 

-H4-A  dialog  box 
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Dialog  boxes  display  error  messages  or  prompts  with  options  for 
answering  them  (see  Figure  7-8)  .  The  dialog  box  shown  here 
permits  users  to  skip  back  and  forth  in  the  database  file. 

-SCREEN-Figure  7-8\mA  dialog  box-ENDFIG- 


Here  is  the  code  for  the  Skip_rec  procedure.  First  it  opens  the 
alert  window  and  prompts  the  user  for  the  number  of  records  to 
skip.  It  stores  the  user's  entry  in  the  variable  numb_2skip, 
closes  the  window,  and  SKIPS  the  specified  number  of  records.  The 
rest  of  the  procedure  displays  error  messages  when  the  user  tries 
to  SKIP  before  the  first  record  or  after  the  last  record.  The 
Show_msg  procedure  called  within  the  CASE  statement  ACTIVATES 
another  window  that  overlays  the  first  exactly. 

-M-PROCEDURE  Skip_rec-L~ 
numb_2skip  3  0-L- 
ACTIVATE  WINDOW  alert-L- 

@  0,0  SAY  " - SKIP  #  of  RECORDS - "-L- 

@  2,0  SAY  "How  many  records  do  you  want  to  skip?" 

@3,0  SAY  "  (Example:  15  or  -5)  ?  "  ;~L~ 

GET  numb_2skip  PICTURE  "9999"-L- 
READ-L- 

DEACTIVATE  WINDOW  alert-L- 
SKIP  numb_2skip-L- 
DO  CASE-L- 

CASE  EOF ( ) -L- 
GO  BOTTOM- L~ 

DO  Screen-L- 
CLEAR  GETS-L- 

DO  Show_msg  WITH  "Last  record  in  VENDORS  file"-L- 
CASE  BOF()-L~ 

DO  Screen- L~ 

CLEAR  GETS-L- 

DO  Show_msg  WITH  "First  record  in  VENDORS  file"-L- 
ENDCASE-L- 
RETURN-N- 

-H2 -WORKING  WITH  BORDERS 

The  SET  BORDER  command  lets  you  globally  specify  the  characters 
used  in  borders  for  menus,  windows,  boxes,  and  lines.  You  can 
define  four  types  of  borders: 

-o-A  single  line  (the  default  --  SET  BORDER  TO  SINGLE) 

-o-A  double  line  (SET  BORDER  TO  DOUBLE) 

-o-An  inverse  video  panel  (SET  BORDER  TO  PANEL) 

-o-An  invisible  border  (SET  BORDER  TO  NONE) -ENDLIST- 
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You  can  also  design  artistic  borders  using  a  border  definition 
string  with  the  SET  BORDER  command.  For  example,  the  following 
code  first  restores  the  borders  to  their  single-line  default 
values,  and  then  defines  single-lined  borders  with  double-lined 
corners.  The  parameters  refer  to  the  top,  bottom,  left,  and  right 
sides  of  the  rectangle,  and  then  to  its  top  left,  top  right, 
bottom  left,  and  bottom  right  corners.  (Using  a  comma  leaves  a 
setting  unchanged.) 

-M-SET  BORDER  TO-L- 

SET  BORDER  TO  ,,,,201,  187,  200,  188-N- 

Options  of  the  DEFINE  BOX  and  DEFINE  WINDOWS  commands  override 
the  global  settings  provided  by  SET  BORDER,  as  shown  earlier  in 
this  chapter. 

-H2 -WORKING  WITH  COLORS 

Some  of  the  code  examples  in  this  chapter  have  included  color 
settings  (see  "Drawing  Lines  on  the  Screen,"  "Drawing  Boxes  on 
the  Screen,"  and  "Defining  a  Window  and  Its  Borders").  These 
examples  used  the  COLOR  option  of  the  individual  commands  to  set 
colors.  dBASE  IV  also  has  global  color  commands,  in  particular 
SET  COLOR  TO,  SET  COLOR  OF  . . .  TO,  and  @  ...  FILL  TO. 

Table  7-1  shows  how  to  set  the  colors  of  many  objects  you  might 
use  in  an  application.  It  does  not  include  options  for 
controlling  the  color  of  Control  Center  objects.  If  your 
application  lets  users  access  the  Control  Center,  use  SET  COLOR 
OF  and  settings  in  your  Config.db  file  to  set  colors  throughout 
the  menu  system  (see  Chapters  2  and  6  of  Language  Reference ) . 


-TABLE-Table  7-l\mSettlng  colors 
To  color  Use 


Screen  forms 

All  parts  of  form 
@ . . . SAYs 
GET  blanks 

User-entered  text 
Message  line 
Navigation  line 
Error  messages 
Help  messages 
Lines 
Boxes 
Border 
Interior 
Text  inside 


SET  COLOR  TO 

@. . .SAY. . .GET  COLOR 

@. . .SAY. . .GET  COLOR 

or  SET  COLOR  OF  FIELDS 
@. . .SAY. . .GET  COLOR  (enhanced  option) 
SET  COLOR  OF  MESSAGE 
SET  COLOR  OF  MESSAGE 
■> 

j 

@. . .TO  COLOR 

@ ...  TO  COLOR 
@ . . . FILL  TO  COLOR 

7 
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Windows 

Border  DEFINE  WINDOW  COLOR 

Interior  DEFINE  WINDOW  COLOR 

Text  inside  ? 

Bar  menus 


Menu  options 

SET 

COLOR 

OF 

MESSAGES 

Dimmed  options 

SET 

COLOR 

OF 

MESSAGES 

Selected  options 

SET 

COLOR 

OF 

HIGHLIGHT 

Highlight  bar 

7 

Pop-up  menus  and  lists 

Border 

SET 

COLOR 

OF 

BORDER 

Interior 

7 

Menu  options 

SET 

COLOR 

OF 

MESSAGES 

Dimmed  options 

SET 

COLOR 

OF 

MESSAGES 

Selected  options 

SET 

COLOR 

OF 

HIGHLIGHT 

Highlight  bar 

7 

Dialog  boxes 

Border 

SET 

COLOR 

OF 

BORDER 

Entry  blank 

SET 

COLOR 

OF 

FIELDS 

Clock 

SET 

COLOR 

OF 

INFORMATION 

Status  bar 

SET 

COLOR 

OF 

INFORMATION-ENDTABLE- 

This  first  routine  provides  the  basic  color  settings  used 
throughout  the  sample  Business  application.  The  ISCOLOR() 
function  determines  whether  the  user's  system  has  a  color  card. 
See  SET  COLOR  in  Language  Reference  for  an  explanation  of  the 
individual  color  settings. 


-M-IF  ISCOLORO- 
c_standard  = 
c_data  = 
c_popup  =* 
c_alert  = 
c_list  = 

c_backg  =■ 
ELSE-L- 

c_standard  » 
c_data  - 
c_popup  =■ 
c_alert  = 
c_list  = 
cbackg  - 
ENDIF-L- 
SET  COLOR  TO  Sc 


L- 

"W/B,BG+/R.B"-L- 

"B/W,R/BG,B"-L~ 

"B/W,GR+/R"-L- 

"GR+/R. B/W, R/G”-L- 

,,W+/G,G/GR,N/GR"-L- 

"R/W-L- 


"W+/N,N/W"-L- 

"W+/N,N/W"-L- 

”W+/N,N/W"-L- 

"W+/N,N/W"~L~ 

"W+/N,N/W"-L- 

"N/W"-L- 

standard.-N- 


The  following  routine  globally  sets  the  colors  for  the  Vendors 
screen  form,  rather  than  using  the  COLOR  option  with  each 
@. . .SAY. . .GET: 


SET  COLOR  TO  Sc_data.-L- 
@  2,24  SAY  "  VENDORS  DATABASE" -L- 

@  6,6  SAY  "VENDOR  NUMBER:"  GET  m->vendor_id  PICTURE  " !999"-L- 
@  9,6  SAY  "NAME:  "  GET  m->vendor  FUNCTION  "!"-L- 
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@ 

10,6 

SAY 

"ADDRESS:" 

GET  m->addressl  v  FUNCTION 

@ 

11,14 

GET 

m->address2 

v  FUNCTION  "!"~L~ 

@ 

12,6 

SAY 

"CITY:  " 

GET 

m->city  v  FUNCTION 

@ 

13,6 

SAY 

"STATE:  " 

GET 

m->state  v  PICTURE  " ! ! "-L- 

@ 

13,30 

SAY 

"ZIP:" 

GET 

m->zip_v-L- 

@ 

15,6 

SAY 

"CONTACT: " 

GET 

m->contact_v 

FUNCTION  " 1 " - L~ 

@ 

16,6 

SAY 

"PHONE:  " 

GET 

m->phone_vend 

PICTURE  '*  (999) 999-9999' 

@ 

16,30 

SAY 

"EXTENSION: 

"  GET 

m->phone_ext 

PICTURE  "9999"-L- 

@ 

17,6 

SAY 

"TERMS :  " 

GET 

m->terms_v 

FUNCTION  '* !  "-L- 

@ 

18,6 

SAY 

"DISCOUNT:" 

GET 

m->discount_v 

PICTURE  "99"-L- 

@ 

18,18 

SAY 

"%"-L- 

SET  COLOR  TO  &c_standard.-N- 

To  vary  from  the  SET  COLOR  TO  definitions  without  changing  the 
global  settings,  define  a  box  around  the  screen  form  and  then 
color  it  with  SET  FILL  TO. 

The  next  example,  which  is  an  excerpt  from  the  Screen  procedure, 
shows  the  color  setup  for  the  Vendors  screen  form.  After  defining 
and  coloring  the  single  and  double  lines  and  boxes  used  in  the 
form,  the  routine  colors  in  the  background  of  the  boxes.  Note 
that  four  separate  @...FILL  TOs  are  required  to  fill  in  the  areas 
around  the  title,  around  the  VENDOR  NUMBER  prompt,  above  the 
horizontal  dividing  line,  and  below  that  line. 

§  1,22  TO  3,53  COLOR  B/W  DCCJBLE-L- 
@5,4  TO  7,27  COLOR  R/W  DOUBLE-L- 
@8,4  TO  19,53  COLOR  R/W-L- 
@  14,5  TO  14,52  COLOR  R/W-L- 
@  2,23  FILL  TO  2,52  COLOR  B/W-L- 
@6,5  FILL  TO  6,26  COLOR  R/W-I.- 
@8,5  FILL  TO  13,52  COLOR  R/W-L- 
@15,5  FILL  TO  18,52  COLOR  R/W-N- 

To  control  the  colors  of  individual  SAYs  and  GETS,  use  the  COLOR 
option  of  @. . .SAY. . .GET.  This  last  routine  shows  the  balance  for 
customers  with  no  balance  due  in  green,  balances  of  less  than 
$1,000  in  yellow,  and  balances  $1,000  or  over  in  red. 

-M-4,30  SAY  "PREVIOUS  BALANCE:  "-L- 
DO  CASE- IN¬ 
CASE  m->oldbalance  >-  1000-L- 

@  14,45  SAY  m->oldbalance  PICTURE  "999,999.99"  COLOR  R/W-L- 
CASE  m->oldbalance  >  0-L- 

@  14,45  SAY  m->oldbalance  PICTURE  "999,999.99"  COLOR  GR+/WH 
CASE  m->oldbalance  <=  0-L- 

@  14,45  SAY  m->oldbalance  PICTURE  "999,999.99"  COLOR  G/W-L- 
ENDCASE-N- 

The  following  code  accomplishes  the  same  thing  in  fewer  lines: 

-M-mcolor  =■  IIF(oldbalance  >-  1000,  "R" ,  IIF(oldbalance  >  0,"GR+","i 
@  14,45  SAY  oldbalance  PICTURE  "999,999.99"  COLOR  Smcolor.-N- 
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Figure  7-1  String  exceeding  box  dlnonelons 


Flgur*  7-2  String  axcMdlng  ulndow  dlnansions 


Record  a*  S 


UENDORS  DATABASE 


|  UENDOR  NUMBER*  3898  | 


NAME*  SOUTHERN  SALES  LTD. 

ADDRESS*  9904  ELN  STREET 

CITY*  SAN  DIEGO 

STATE*  CA  ZIP*  40444 


CONTACT'  TIN  DAUIDSON 

PHONE*  (800)292-5100  EXTENSION*  9200 
TERNS*  NET  30 
DISCOUNT*  BX 


—  OPTION  MENU 
Add  Nau  Racord 
Find  Racord 
Edit  Racord 
Naxt  Racord 
Prav  Racord 
Top  Racord 
Botton  Racord 
Skip  ■  of  Racords 
Dalata  Racord 
List  Racords 
Raport/Prlnt 
Count  s  Racords 
Halp 

IndaxXRaindax 

Quit 
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figure  7-4  LISTlng  ti 
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Record  ■>  16 
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-HI- DESIGNING  MENUS  AND  LISTS 

This  chapter  explains  how  to  use  the  dBASE  IV  menu-building 
commands  to  create  a  menu  interface  for  your  application.  If  you 
prefer,  you  can  use  the  applications  generator  provided  with 
dBASE  IV  to  build  menu  interfaces  (see  Using  the  dBASE  IV 
Applications  Generator ) . 

-H2-WHAT  THIS  CHAPTER  COVERS 

This  chapter  shows  you  how  to  create  a  menu  interface  for  your 
application.  The.  topics  it  covers  are: 

-o-Defining  a  pop-up  menu 

-o-Defining  a  horizontal  bar  menu 

-o-Defining  a  pull-down  menu 

-o-Defining  a  list 

-o-Defining  a  main  menu-ENDLIST- 

The  emphasis  is  on  how  to  build  a  menu  system,  rather  than  how  to 
design  one.  See  "The  Basics"  in  Using  the  dBASE  IV  Applications 
Generator  for  a  discussion  of  the  principles  of  menu  design. 

-H2 -OVERVIEW 

The  dBASE  IV  menu-building  commands  and  functions  allow  you  to 
design  a  variety  of  menu  objects.  Figure  8-1  identifies  these 
objects  in  a  generic  menu  interface.  Note  the  distinction  between 
a  horizontal  bar  menu  and  pop-up  or  pull-down  menus. 

-ILLUS-Figure  8-l\mNames  of  menu  ob j ects-ENDFIG- 

The  next  several  sections  of  this  chapter  show  how  to  build 
pop-up  menus.  "Defining  Other  Menu  Objects"  below  shows  how  to 
code  horizontal  bar  menus,  pull-down  menus,  lists,  and  an 
application  main  menu. 

The  main  steps  in  coding  a  menu  system  are: 

-#-l.  Define  each  menu  and  its  items. 

~#~2 .  Specify  what  each  menu  item  does. 

-#~3.  Activate  the  main  menu. 

-#-4.  Deactivate  and  release  menus  when  no  longer 
needed. -ENDLIST- 

-WARNING-As  with  memory  variables,  dBASE  IV  overwrites  menu  and 
menu  item  definitions  of  the  same  name  without  warning. -ENDBOX- 
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You  can  save  development  time  by  using  the  applications  generator 
to  define  the  menu  system  for  your  application.  The  applications 
generator  creates  .gen  files  containing  dBASE  code,  which  you  can 
edit  directly. 

-WARNING- I f  you  change  a  .gen  file  in  the  program  editor  and 
subsequently  make  and  save  changes  in  the  applications  generator,  , 
your  changes  to  the  .gen  file  will  be  overwritten.  To  save 
development  time,  build  the  menu  system  in  the  applications 
generator.  Then  fine-tune  it  with  code  embeds  or  in  the  program 
editor. -ENDBOX- 

-H2 -DEFINING  A  POP-UP  MENU 

A  pop-up  menu  is  a  list  of  selectable  items  framed  by  a  border. 
Users  select  items  by  typing  the  first  letter  of  the  item  name  or 
moving  the  highlight  to  the  item  and  pressing  -RETURN-. 

-H3~Defining  the  Pop-up  Menu  and  its  Items 

DEFINE  POPUP  and  DEFINE  BAR  define  a  pop-up  menu  and  its  items. 

(A  menu  item,  or  prompt,  is  the  text  string  describing  the  menu 
choice  to  the  user.)  The  following  code  defines  the  pop-up  menu 
used  throughout  the  Business  application  in  your  sample  files. 

DEFINE  POPUP  provides  the  upper  left  and  lower  right  screen 
coordinates  for  the  pop-up.  If  you  omit  the  bottom  right 
coordinate,  dBASE  IV  figures  out  the  dimensions  fcr  you.  dBASE 
truncates  item  names  defined  with  DEFINE  BAR  that  are  wider  than 
the  menu  width  and  scrolls  the  items  vertically  if  there  are  too 
many  to  fit.  MESSAGES  defined  with  either  command  appear  centered 
at  the  bottom  of  the  screen.  dBASE  IV  truncates  messages  longer 
than  79  characters. 

Use  DEFINE  BAR  to  define  menu  prompts.  This  command  refers  to  the 
lines  of  the  pop-up  menu  by  number:  the  first  (top)  line  is  bar 
1,  the  second  bar  2,  and  so  on.  Be  sure  to  define  the  items  in 
vertical  order  of  appearance;  the  highlight  will  navigate  them  in 
ascending  numeric  order. 

Note  that  bar  1  in  this  example  is  used  for  the  menu  title  rather 
than  an  item.  The  SKIP  keyword  causes  the  highlight  to  skip  over 
it,  since  it  is  not  a  selectable  menu  item. 


-M-PROCEDURE  Bar_def-L~ 

DEFINE  POPUP  main_mnu  FROM  2,58  TO  19,79  MESSAGE  ;-L- 

"Press  first  letter  of  item  or  highlight  and  press  <Enter>"-L- 
DEFINE  BAR  1  OF  main_mnu  PROMPT  "==  OPTION  MENU  ==  "  SKIP-L- 

DEFINE  BAR  2  OF  main_mnu  PROMPT  "Add  New  Record"~L~ 

DEFINE  BAR  3  OF  mainjmnu  PROMPT  "Find  Record"-L~ 

DEFINE  BAR  4  OF  main  mnu  PROMPT  "Edit  Record"~L~ 
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DEFINE 

BAR 

DEFINE 

BAR 

DEFINE 

BAR 

DEFINE 

BAR 

DEFINE 

BAR 

DEFINE 

BAR 

DEFINE 

BAR 

DEFINE 

BAR 

DEFINE 

BAR 

DEFINE 

BAR 

DEFINE 

BAR 

DEFINE 

BAR 

RETURN- N~ 

5  OF  main_mnu  PROMPT  "Next  Record"~L~ 

6  OF  main_mnu  PROMPT  "Prev  Record"-L- 

7  OF  main_mnu  PROMPT  "Top  Record"-L- 


8  OF  main_mnu  PROMPT 

9  OF  mainjmnu  PROMPT 

10  OF  mainjmnu  PROMPT 

11  OF  main_mnu  PROMPT 

12  OF  main_mnu  PROMPT 

13  OF  main_mnu  PROMPT 

14  OF  main_mnu  PROMPT 

15  OF  mainjmnu  PROMPT 

16  OF  main  mnu  PROMPT 


Bottom  Record"-L- 
Skip  #  of  Records"-L- 
"Delete  Record"-L- 
"List  Records"-L- 
"Report/Print"~L- 
" Count  #  Records"~L~ 
"Help"-L- 

"Index/Reindex"-L- 

"Quit"~L~ 


-NOTE-dBASE  IV  displays  the  prompts  flush  left  against  the  pop-up 
border.  If  you  want  a  space  between  the  border  and  the  first 
character  of  prompt,  include  it  in  the  prompt  string:  -R-DEFINE 
BAR  2  OF  main_mnu  PROMPT  "  Add  New  Record" .  -ENDBOX- 

Variation  —  Putting  blank  lines  between  items 

If  you  want  a  blank  line  to  appear  between  two  menu  items,  skip 
the  corresponding  bar  number.  The  highlight  will  automatically 
skip  over  the  intervening  blank  line.  For  example,  DEFINE  BAR  18 
immediately  after  bar  16  to  skip  bar  17. 

Variation  —  Skipping  based  on  a  condition 

You  can  make  the  highlight  skip  a  particular  item  in  certain 
conditibns.  The  following  modifications  of  the  item  definitions 
provided  above  make  the  Find,  Edit,  and  Count  items  unavailable 
when  there  are  no  records  ii  the  database  file: 

-M-DEFINE  BAR  3  OF  main_mnu  PROMPT  "Find  Record"~L~ 

SKIP  FOR  RECCOUNT()  =  0-L- 
DEFINE  BAR  4  OF  mainjmnu  PROMPT  "Edit  Record"~L~ 

SKIP  FOR  RECCOUNTO  =  0-L- 

DEFINE  BAR  13  OF  mainjmnu  PROMPT  "Count  #  Records" ;~L~ 

SKIP  FOR  RECCOUNTO  =  0-N- 

~H3~Specifying  What  the  Menu  Options  Do 

ON  SELECTION  POPUP  specifies  a  procedure  that  executes  when  a 
pop-up  menu  first  appears.  That  procedure  contains  the 
instructions  for  what  each  menu  item  does. 

In  the  following  code,  the  pop-up  menu  executes  the  Barpop 
procedure.  CASE  statements  within  Barpop  define  what  each  item 
of  main_mnu  does.  Note  that  a  menu  item  can  DO  a  procedure, 
execute  a  dBASE  IV  command,  or  even  ACTIVATE  another  pop-up  menu 
(see  "Activating  the  Pop-up  Menu") .  Because  bar  1  is  the  menu 
title,  the  CASES  start  with  bar  2. 
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Note  that  to  color  a  pop-up  menu  you  SET  COLOR  TO  the  desired 
color  before  executing  the  menu  procedure.  To  keep  the  menu  color 
from  spilling  into  the  rest  of  your  application,  reset  the 
default  colors  before  leaving  the  pop-up  procedure. 

The  Sample  Programming  Code  booklet  includes  complete  code  for 
the  many  procedures  called  in  this  routine. 

-M-ON  SELECTION  POPUP  main_mnu  DO  Barpop-L- 

SET  COLOR  TO  Sc_popup.-L- 

-L- 

PROCEDURE  Barpop-L- 
DO  CASE-L- 

CASE  BAR ( )  =  2-L- 
DO  Add_new-L- 
CASE  BAR( )  =  3-L- 
DO  Find_rec~L~ 

CASE  BAR()  =  4-L- 
DO  Edit-L- 
CASE  BAR()  =  5-L- 
DO  Next_rec~L~ 

CASE  BAR ( )  =  6-L- 
DO  Prev_rec-L- 
CASE  BAR( )  =  7-L- 
GO  TOP-L- 
CASE  BAR()  =  8-L- 
GO  BOTTOM- L- 
CASE  BAR( )  =  9-L- 
DO  Skip_rec-L- 
CASE  BAR( )  =  10-L- 
DO  Eraser-L- 
CASE  BARf)  =  11-L- 
DO  List_rec-L- 
CASE  BAR( )  =  12-L- 

SET  COLOR  TO  &c_popup.-L- 
ACTIVATE  POPUP  rpt_mnu~L~ 

CASE  BAR( )  =  13-L- 
DO  Kount-L- 
CASE  BAR ( )  =  14-L- 

SET  COLOR  TO  4c_standard. -L- 
DO  Helper-L- 
CASE  BAR( )  =  15-L- 
DO  Indexer-L- 
CASE  BAR( )  =  16-L- 
DO  Exit_now-L- 
ENDCASE-L- 

SET  COLOR  TO  Sc_standard.-L- 
RETURN-N- 

-H3 -Activating  the  Pop-up  Menu 

Only  one  line  of  code  is  required  to  activate  the  defined  pop-up 
menu: 
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-M-ACTIVATE  POPUP  main_mnu-N~ 

Be  sure  that  your  code  has  already  defined  the  pop-up  menu  before 
activating  it.  Thus,  the  order  that  the  code  must  follow  is: 

-M-DO  Bardef-L- 

ON  SELECTION  POPUP  main_mnu  DO  Barpop-L- 

ACTIVATE  POPUP  main_mnu-L- 

\m~L~ 

PROCEDURE  Bardef-L- 

<procedure  code  shown  above>-L- 
RETURN-L- 
\m~L~ 

PROCEDURE  Barpop-L- 

<procedure  code  shown  above>-L- 
RETURN-N- 

dBASE  IV  checks  you  pop-up  coordinates  when  you  ACTIVATE  the 
POPUP,  not  when  you  DEFINE  POPUP. 

-NOTE-The  previous  example  is  a  simplification  of  the  menu 
definition  code  in  the  Business  application.  The  -R-Sample 
Programming  Code-I-  booklet  contains  the  complete  code,  which 
includes  several  pop-up  menu  definitions  and  several  procedures 
defining  what  their  items  do.-ENDBOX- 

-H3-Deactivating  and  Releasing  the  Pop-up  Menu 

When  you  ACTIVATE  a  POPUP  in  your  menu  system,  dBASE  IV  leaves 
other  pop-ups  that  you've  already  activated  on  the  screen  and 
places  the  new  one  on  top  of  them.  It  is  up  to  you  to  DEACTIVATE 
POPUPs  when  you  no  longer  need  them  to  show. 

-TIP-When  you  DEACTIVATE  POPUP,  the  pop-up  menu  -R-and  any  menus 
and  procedures  called  by  it-I-  terminate.  In  the  case  of 
procedures,  any  remaining  code  is  not  executed  (as  if  you  had 
EXITed  the  procedure) .  DEACTIVATE  POPUP  returns  control  to  the 
level  at  which  the  pop-up  menu  was  called. -ENDBOX- 

CLEAR  or  RELEASE  menu  definitions  from  memory  when  you  no  longer 
need  them.  You  cannot  CLEAR  or  RELEASE  menus  while  they  are 
active,  so  DEACTIVATE  them  first. 

-H3-Providing  Menu  Help 

Using  ON  KEY  in  conjunction  with  the  menu-building  commands,  you 
can  provide  users  of  your  application  with  context-sensitive  menu 
help.  The  following  routine  provides  help  on  a  given  menu  item 
when  the  user  highlights  it  and  presses  -F1-.  The  POPUP () 
functions  identify  the  various  menus  in  the  system,  while  the 
BAR()  functions  identify  the  items  in  each  menu. 

ON  KEY  FI  DO  Menuhelp-L- 
-L~ 
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PROCEDURE  Menuhelp-L- 

ACTIVATE  WINDOW  Help_w~L~ 

DO  CASE-L- 

CASE  POPUP ()  =  " ma i n_mnu "  -  L- 
DO  CASE-L- 

CASE  BAR( )  =  2-L- 

?  "Add  new  record  to  database  file  in  index  order"- 
CASE  BAR ( )  =  3-L- 

?  "Find  or  retrieve  record  by  searching  key  field"- 

•  -L- 

. < BAR ( ) s  and  help  text  for  items  4  -  15>-L- 

•  -L- 

CASE  BAR()  =  16()~L~ 

?  "Exit  to  Main  Menu"-L- 
ENDCASE-L- 

CASE  POPUP ()  =  "rept_mnu"-L~ 

DO  CASE-L- 

CASE  BAR ( )  =  2-L- 

?  "Print  list  of  items  from  this  database  file"-L~ 
CASE  BAR( )  =  3-L- 

?  "Print  mailing  list  for  this  database  file"-L~ 
CASE  BAR()  =  4-L- 

?  "Exit  to  Options  menu"-L~ 

ENDCASE-L- 

.-L- 

•<POPUP()s  and  CASE  statements  for  other  menus>~L~ 

.-L- 

ENDCASE-  L- 

WAIT  "Press  any  key  to  exit  Help"~L~ 

DEACTIVATE  WINDOW  Help_w-L- 
RETURN-N- 


-H2-DEFINING  OTHER  MENU  OBJECTS 

This  section  shows  how  to  define  a  horizontal  bar  menu,  a 
pull-down  menu,  a  list,  and  a  main  application  menu. 

-NOTE-Many  menus  use  dialog  boxes  to  prompt  the  user  for 
information.  "More  Uses  of  Windows"  in  Chapter  7  shows  how  to 
code  a  dialog  box.-ENDBOX- 

-H3-Defining  a  Horizontal  Bar  Menu 

You  can  define  a  horizontal  bar  menu  that  runs  across  the  top  of 
the  screen,  as  many  spreadsheet  menus  do.  Figure  8-2  shows  a 
horizontal  bar  menu. 

-ILLUS-Figure  8-2\mA  horizontal  bar  menu-ENDFIG- 


The  dBASE  IV  menu-building  commands  for  horizontal  bar  menus  are 
similar  to  those  for  pop-up  menus,  as  you  can  see  in  Table  8-1. 
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-TABLE-Table  8-l\mCommands  for  horizontal  bar  and  pop-up  menus 
Operation  Horizontal  Bar  Menu  Pop-up  Menu 


Naming  the  menu 
Naming  the  prompts 
Defining  the  actions 

Opening  the  menu 
Showing  an  inactive  menu 
Closing  the  menu 
Releasing  the  menu 
definitions 

Returning  the  menu  name 
Returning  the  internal 
item  name 

Returning  the  external 
item  name  (prompt) 


DEFINE  MENU 
DEFINE  PAD 
ON  PAD1  or 
ON  SELECTION  PAD 
ACTIVATE  MENU 
SHOW  MENU 
DEACTIVATE  MENU 
CLEAR  MENUS  or 
RELEASE  MENUS 
MENU() 

PAD() 

PROMPT () 


DEFINE  POPUP 
DEFINE  BAR 
ON  SELECTION  POPUP 

ACTIVATE  POPUP 
SHOW  POPUP 
DEACTIVATE  POPUP 
CLEAR  POPUPS  or 
RELEASE  POPUPS 
POPUP ( ) 

BAR() 

PROMPT ( ) 


1.  Use  ON  PAD  with  horizontal  bar  menus  that  have  attached 
pull-downs  (see  next  section) . -ENDTABLE- 


The  following  procedure  defines  the  horizontal  bar  menu  shown  in 
Figure  8-2  above,  which  is  a  variation  of  the  main  pop-up  menu 
used  throughout  the  Business  application. 


The  DEFINE  MENU  and  DEFINE  PAD  commands  define  the  bar  menu  and 
its  items.  The  AT  coordinates  position  the  menu  items  on  the 
second  row  of  the  screen.  (By  varying  the  coordinates,  you  can 
place  the  menu  items  anywhere  you  like  on  the  screen.)  dBASE  IV 
automatically  adds  a  blank  space  to  the  left  and  right  of  the 
item  name.  The  order  in  which  you  DEFINE  the  PADS  determines  the 
order  in  which  the  highlight  accesses  them. 


The  ON  SELECTION  PAD  commands  ACTIVATE  a  pop-up  menu  or  DO  a 
procedure  for  each  item  in  the  bar  menu.  (Assume  that  you  have 
already  defined  these  pop-ups  and  procedures  in  your  code.) 


-M-PROCEDURE  Menu_def-L- 
DEFINE  MENU  barmenu  ;-L~ 

MESSAGE  "To  choose  item,  highlight  and  press  <Return>"-L- 
DEFINE  PAD  add_del  OF  barmenu  PROMPT  "Add/delete"  AT  2,1  ;-L- 
MESSAGE  "Add,  change,  or  delete  records  in  current  database"-L~ 
DEFINE  PAD  movefind  OF  barmenu  PROMPT  "Move/Find"  AT  2,14  ;-L- 
MESSAGE  "Go  to  selected  record"-L- 
DEFINE  PAD  listprin  OF  barmenu  PROMPT  "List/Print"  AT  2,26  ;-L- 
MESSAGE  "List  data  to  screen,  file,  or  printer"-L- 
DEFINE  PAD  cnt_indx  OF  barmenu  PROMPT  "Count/Index"  AT  2,39  ;-L- 
MESSAGE  "Count  records  or  index  the  database  file"-L- 
DEFINE  PAD  help  OF  barmenu  PROMPT  "Help"  AT  2,53  ;-L- 
MESSAGE  "Get  help  on  how  to  use  this  program" -L- 
DEFINE  PAD  exit  OF  barmenu  PROMPT  "Exit"  AT  2,61  ;~L~ 

MESSAGE  "Exit  this  program"-L~ 
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ON  SELECTION  PAD  add_del  OF  barmenu  ACTIVATE  POPUP  add  del-L- 
ON  SELECTION  PAD  movefind  OF  barmenu  ACTIVATE  POPUP  movefind-L- 

ON  SELECTION  PAD  listprin  OF  barmenu  ACTIVATE  POPUP  listprin-L- 

ON  SELECTION  PAD  cnt_indx  OF  barmenu  ACTIVATE  POPUP  cnt  indx-L- 

ON  SELECTION  PAD  help  OF  barmenu  DO  Helper-L- 

ON  SELECTION  PAD  exit  OF  barmenu  DO  Exit  now-L- 


ACTIVATE  MENU  barmenu  PAD  add_del~L~ 
RETURN-N- 


-NOTE-The  PAD( )  function  returns  the  prompt  pad  name  of  the  most 
recently  selected  menu  item  The  prompt  pad  name  is  an  internal 
label  that  you  assign  when  you  DEFINE  PAD.  It  is  not  the  same  as 
the  prompt  that  appears  on  the  screen.  If  the  user  presses 
-ESC — I-  to  exit  the  menu,  PAD()  returns  a  null  string. -ENDBOX- 

-H3-Defining  a  Pull-down  Menu 

A  pull-down  menu  is  a  pop-up  menu  that  pulls  down  from  a 
horizontal  bar  menu.  The  dBASE  IV  Control  Center  uses  pull-down 
menus.  Figure  8-3  shows  a  pull-down  menu  based  on  the  Business 
application,  with  the  first  pull-down  open. 

-ILLUS-Figure  8-3\mA  pull-down  menu-ENDFIG- 


Pull-down  menus  differ  from  pop-up  menus  in  one  essential 
respect.  Simply  moving  the  highlight  to  an  item  on  the  bar  menu 
without  pressing  -RETURN-  opens  the  attached  pull-down.  In  a 
pop-up  menu  (or  a  horizontal  bar  menu  without  attached 
pull-downs) ,  the  user  must  select  an  item  to  display  a  submenu. 

The  following  code  fragment  replicates  the  last  part  of  the 
previous  routine,  except  that  the  first  four  ON  SELECTION  PAD 
commands  have  been  changed  to  ON  PADS.  This  causes  the 
corresponding  pull-downs  to  appear  automatically  when  the  user 
moves  the  highlight  to  the  corresponding  bar  menu  item. 

-M-ON  PAD  add_del  OF  barmenu  ACTIVATE  POPUP  add_del-L~ 

ON  PAD  movefind  OF  barmenu  ACTIVATE  POPUP  movefind-L- 
ON  PAD  listprin  OF  barmenu  ACTIVATE  POPUP  listprin-L- 
ON  PAD  cnt_indx  OF  barmenu  ACTIVATE  POPUP  cnt_indx-L- 
ON  SELECTION  PAD  help  OF  barmenu  DO  Helper-L- 
ON  SELECTION  PAD  exit  OF  barmenu  DO  Exit_now-N- 

Variation  —  Disabling  a  pull-down  menu 


Sometimes,  you  don't  want  the  user  to  be  able  to  access  the 
pull-down  menu  attached  to  a  given  horizontal  bar  menu  item.  For 
example,  you  might  want  ... 
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In  the  following  code,  the  command  ON  PAD  3  with  no  argument 
disables  the  third  menu  item,  so  that  highlighting  it  does  not 
open  the  corresponding  pull-down. 

((Replace  with  real  code)} 

-M-ON  PAD  1  OF  Barmenu  ACTIVATE  POPUP  . ..-L- 

ON  PAD  2  OF  Barmenu  ACTIVATE  POPUP 

ON  PAD  3  OF  Barmenu-L- 

ON  PAD  4  OF  Barmenu  ACTIVATE  POPUP 

ON  PAD  5  OF  Barmenu  ACTIVATE  POPUP  . . . ~N~ 

-H3-Defining  a  List 

To  dBASE  IV,  a  list  is  just  a  special  brand  of  pop-up  menu  that 
contains  variable  items  rather  than  fixed  ones.  You  can  create 
three  kinds  of  lists: 

-o-File  lists,  containing  the  names  of  the  files  on  disk  or  in 
the  current  catalog 

-o-Field  lists,  containing  the  names  of  the  active  fields  defined 
by  SET  FIELDS 

-o-Record  lists,  containing  the  contents  of  each  record  in  a 
f ield-ENDLIST- 

As  with  regular  pop-up  menus,  DEFINE  POPUP  creates  a  list.  This 
time,  however,  you  must  supply  an  argument  for  the  PROMPT: 

-M-DEFINE  POPUP  files  FROM  2,20  TO  20,50  PROMPT  FILES  LIKE  * . DBF-N- 

You  don't  need  to  define  the  items  in  a  list  explicitly,  as  you 
did  for  pop-up  menu  items.  Once  you've  specified  the  type  of  list 
you  want,  dBASE  IV  provides  the  items.  Since  a  list  is  just  a 
special  type  of  pop-up  menu,  you  display  a  list  with  ACTIVATE 
POPUP. 

-H3-Defining  a  Main  Menu 

A  main  menu  is  the  top-level  menu  of  an  application.  It  calls  all 
other  menus  in  the  program,  and  users  enter  and  exit  the  program 
through  the  main  menu.  The  Business  application  uses  the  main 
menu  shown  in  Figure  8-4. 

-ILLUS-Figure  8-4\mA  typical  main  menu-ENDFIG- 


Here  is  the  code  for  this  main  menu.  Note  that  the  code  is  nested 
in  a  DO  WHILE  . T.  loop,  which  forces  dBASE  to  loop  continually 
back  to  the  main  menu  until  the  user  exits  by  choosing  QUIT. 
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The  CASE  statements  get  the  user's  entry  of  a  menu  choice  and 
execute  the  appropriate  procedure  for  each  choice.  The  Def_menu 
procedure  defines  the  menu  options,  as  explained  under  "Defining 
a  Pop-up  Menu"  above. 

The  Sample  Programming  Code  booklet  contains  the  complete  code 
for  the  many  procedures  called  by  this  program. 


-M-DO  Def_menu-L- 
DO  WHILE  .T.-L- 
CLEAR-L- 

ON  SELECTION  POPUP  main_mnu  DEACTIVATE  POPUP-L- 
ACTIVATE  POPUP  main_mnu~L~ 

DO  CASE-L- 

CASE  BAR( )  =  17-L- 
EXIT-L- 

CASE  BAR  ( )  =  7-L- 
DO  Employee-L- 
CASE  BAR ( )  =  8-L- 
DO  Cust-L- 
.-L- 

.  <remaining  CASE  statements>-L- 
.-L- 

ENDCASE-L- 

ENDDO-L- 

QUIT-L- 

\m-L- 

PROCEDURE  Mainproc-L- 
CLEAR-L- 
CLEAR-L- 
RETURN-L- 
\m-L- 

PROCEDURE  Def_menu-L- 

DEFINE  POPUP  main_mnu  FROM  1,24  TO  20,56;~L~ 

MESSAGE  "Please  choose  a  database  file  or  utility"~L~ 


DEFINE 

BAR 

2 

OF 

main 

mnu 

PROMPT 

II 

A-T 

FURNITURE  INDUSTRIES"  S 

DEFINE 

BAR 

3 

OF 

main 

mnu 

PROMPT 

It 

MAIN  MENU"  SKIP-L- 

DEFINE 

BAR 

4 

OF 

main 

mnu 

PROMPT 

II 

:=====================•• 

DEFINE 

BAR 

6 

OF 

main 

mnu 

PROMPT 

II 

Databases:"  SKIP-L- 

DEFINE 

BAR 

7 

OF 

main 

mnu 

PROMPT 

II 

1. 

EMPLOYEES "-L- 

DEFINE 

BAR 

8 

OF 

main 

mnu 

PROMPT 

II 

2. 

CUSTOMERS "-L- 

DEFINE 

BAR 

9 

OF 

main 

mnu 

PROMPT 

II 

3. 

VENDORS "-L- 

DEFINE 

BAR 

10 

OF 

main 

mnu 

PROMPT 

II 

4. 

FURNITURE  INVENTORY"- 

DEFINE 

BAR 

ii 

OF 

main 

mnu 

PROMPT 

It 

5. 

ORDER  TRANSACTIONS  "  -  L 

DEFINE 

BAR 

12 

OF 

main 

mnu 

PROMPT 

II 

6. 

ACCT  RECEIVABLE"-!- 

DEFINE 

BAR 

14 

OF 

main 

mnu 

PROMPT 

It 

Utilities:"  SKIP-L- 

DEFINE 

BAR 

15 

OF 

main 

mnu 

PROMPT 

II 

R. 

REPORTS "-L- 

DEFINE 

BAR 

16 

OF 

main 

mnu 

PROMPT 

II 

B. 

BACK/RESTORE  DATA"-L~ 

DEFINE 

BAR 

17 

OF 

main 

mnu 

PROMPT 

II 

Q. 

QUIT"~L~ 

RETURN-N- 
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-COMMENT-If  you're  maintaining  a  dBASE  III  PLUS  program,  you 
might  encounter  this  traditional  code  for  a  main  menu. 

-M-choice  »  "  11 -L- 
standard  =■  "W+/B,  BG+/R"~L~ 
red_fill  «  "W+/R"-L~ 
yello_fill  =  "GR+/W"~L- 
\ra-L- 

DO  WHILE  .T.-L- 

SET  COLOR  TO  &standard.-L~ 

CLEAR-L- 
@  1,0-L- 
TEXT-L- 
\m-L- 

A-T  FURNITURE  INDUSTRIES-L- 
MAIN  MENU-L- 

====================  ====== -L~ 

\m~L- 

Databases:-L~ 

1.  EMPLOyEES-L- 

2.  CUSTOMERS -L- 

3 .  VENDORS-L- 

4 .  FURNITURE  INVENTORY-L- 

5 .  ORDERS  TRANS ACTIONS-L- 

6.  ACCT.  RECEIVABLE-L- 

\m-L- 

Utilities: -L- 
R.  REPORTS-L- 
B.  BACKUP/RESTORE  DATA-L- 
Q.  QUIT-L- 

ENDTEXT-L- 

\m-L- 

§  7,20  TO  7,55-L- 
@  15,20  TO  15,55-L- 
@  5,20  TO  20,55  DOUBLE-L- 
@  6,21  FILL  TO  7,54  COuOR  &red_f ill . -L- 
@  8,21  FILL  TO  19,54  COLOR  &yello_f ill . -L- 
\m-L~ 

choice  =  "  "-L- 

e  22,29  SAY  "CHOICE:  "  GET  choice  PICTURE  ;-L- 

DEFAULT  "Q"  ;-L- 

MESSAGE  "Please  choose  a  databare  file  or  utility. "-L- 
READ-L- 
\m-L~ 

@  23,00  SAY  "Loading  program,  please  wait..."-L- 
-\mL- 

DO  CASE-L- 

CASE  choice  =  "Q"-L- 
QUIT-L- 

CASE  choice  =  "1"-L- 
DO  Employee-L- 
CASE  choice  =  «2”-h~ 

DO  Cust-L- 
.-L- 
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.  cremaining  CASE  statements>~L~ 
.  ~L~ 

ENDCASE-L- 

ENDDO-L- 

CLEAR- N--ENDCOM- 
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-HI- INPUT:  GETTING  DATA  FROM  THE  USER 

To  get  information  from  someone,  you  ash  questions  and  receive 
answers.  Application  programs  also  ask  questions  and  get  answers, 
using  the  screen  and  keyboard  to  communicate.  They  format  the 
data  entered  by  the  user  for  display,  evaluate  it  to  prevent  data 
entry  errors,  and  enter  the  validated  data  into  the  database. 

-H2-WHAT  THIS  CHAPTER  COVERS 

This  chapter  describes  methods  for  getting  information  from  the 
user  within  dBASE  IV  application  programs.  You'll  see  how  to 
obtain  data  from  the  user,  format  the  data  for  display,  and 
evaluate  the  data  before  accepting  it.  Note  that  entering  data 
into  the  database  is  a  separate  topic,  since  the  program  must 
first  evaluate  the  data  and  do  error  processing. 

The  specific  topics  covered  in  this  chapter  are: 

-o-Screen  coordinates  and  relative  addressing 

-o-Getting  data  with  and  without  screen  forms 

-o-Getting  data  from  an  array 

-o-Formatting  data  entry  screens 

-o-Customizing  Browse  tables 

-o-Formatting  data 

-o-Checking  data  for  errors 

-o-Processing  keypresses 

-o-Helping  the  user 

-o-Entering  data  into  and  deleting  data  from  the  database 
-o-Creating  multi-file  forms 
-o-Working  with  large  files. -ENDLIST- 
-H2-SCREEN  COORDINATES  AND  RELATIVE  ADDRESSING 

The  screen  display  is  a  grid  of  evenly  spaced  horizontal  rows  and 
vertical  columns.  The  rows  and  columns  are  numbered  from  the  top 
of  the  screen  down  and  from  left  to  right.  Numbering  starts  with 
0,  rather  than  1.  For  example,  1,3  means  the  second  row,  fourth 
column. 
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The  @ . . . SAY . . . GET  command  positions  characters  on  the  screen  by 
providing  their  screen  coordinates.  A  screen  coordinate  consists 
of  the  row  number  followed  by  the  column  number.  For  example  @ 
1,5  SAY  <expC>  positions  the  character  string  on  the  second  row 
and  the  sixth  column. 

dBASE  uses  the  ROW()  and  COL()  functions  for  relative  addressing , 
that  is,  to  position  a  screen  coordinate  relative  to  an  already 
existing  one.  ROW()  and  COL()  return  the  current  screen  row  and 
column  coordinates.  ROW()  +  1  means  "one  row  below  the  current 
row."  You  can  substitute  the  $  symbol  for  either  ROW()  or  COL(). 

-M-@  ROW ( ) ,  COL()  SAY  <"expl">  44  Or:  @  $,$ 

@  ROW ( ) + 1 ,  C0L()+3  SAY  <"exp2">  44  Or:  @  $+1,  $+3  ...-N- 

When  using  relative  addressing,  be  careful  not  to  exceed  the 
screen  coordinates. 

-H2-GFTTING  DATA  WITH  SCREEN  FORMS 

Screen  format  files  can  arrange  prompts  and  blanks  on  the  screen 
to  simulate  paper  forms  already  familiar  to  end-users.  Using  the 
dBASE  IV  forms  generator  to  prototype  screen  forms  will  save  you 
time  figuring  out  exact  screen  coordinates.  You  can  access  it 
from  the  Control  Center,  or  by  entering  CREATE  SCREEN  <filename> 
at  the  dot  prompt.  ( Using  the  Menu  System  describes  the  forms 
generator  in  detail.) 

-NOTE-You  cannot  create  multiple-file  forms  with  the  forms 
generator.  "Creating  Multi-file  Forms"  later  in  this  chapter 
explains  how  to  code  them. -ENDBOX- 

~H3~Looking  at  the  Code  from  a  Screen  Form 

After  prototyping  your  screen  form  in  the  forms  generator,  list 
the  code  by  entering  MODIFY  COMMAND  c.fmt  filename>.  Figure  9-1 
shows  the  code  for  a  screen  form  next  to  the  form  itself. 

The  format  file  has  three  parts:  an  initialization  section,  a 
forms  control  section,  and  a  termination  section.  The 
initialization  commands  set  up  the  environment  for  the  form.  The 
forms  control  commands  determine  how  the  actual  form  appears  on 
the  screen.  The  termination  code  restores  the  default 
environment. 


In  the  following  example,  ...  The  GETS  store  data  entered  by  the 
user  into  fields  in  the  database  file,  or  in  memory  variables 
defined  earlier.  The  READ  command  activates  the  data  at  the 
appropriate  time. 

You  can  accumulate  only  128  GETs  at  a  time  (unless  you  change 
this  limit  with  the  GETS  command  in  Config.db) .  The  READ  command 
automatically  clears  the  GETS  after  reading  them. 
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-ILLUS-Figure  9-l\mA  screen  form  with  code-ENDFIG- 


-M-SET  COLOR  TO  B/W, R/BG , B-L- 
§  4,8  FILL  TO  10,64  COLOR  R/W-L- 
§  4,8  TO  10,64  COLOR  R/W-L- 
§  2,28  FILL  TO  4,50  COLOR  B/W-L- 
§  2,28  TO  4,50  DOUBLE  COLOR  B/W-L- 
\m-L- 

§  3,30  SAY  " INVENTORY" -L- 

§  5,11  SAY  "Vendor  ID:  "  GET  Vendor_id  PICTURE  "!999"-L- 
§  6,11  SAY  "Part  ID:  "  GET  Part_id  FUNCTION  "!"~L~ 

§7,11  SAY  "Part  name:  "  GET  Partname  FUNCTION  "!"-L- 
§  8,11  SAY  "Description:"  GET  Descrip  FUNCTION  "!"-L- 
§9,11  SAY  "Cost:  $  "  GET  Cost  PICTURE  "99 , 999 . 99"-L- 

§  9,38  SAY  "Quantity  on  hand:"  GET  Qty_onhand  PICTURE  "9,999"~N~ 

~H3~Modifying  the  Screen  Format  File 

The  forms  generator  produces  two  files:  a  forms  design  (.scr) 
file  containing  the  internal  code  used  by  the  generator,  and  a 
format  (.fmt)  file  containing  dBASE  code.  You  can  change  the  code 
in  the  .fmt  file  directly,  using  the  MODIFY  COMMAND  editor. 

You  might  wish  to  modify  the  format  file  directly  in  order  to: 

-o-Initialize  memory  variables  used  in  the  file 

-o-Vary  the  location  of  the  READ  command 

-o-Control  cursor  movement  around  the  form-ENDLIST- 

-WARNING-If  you  change  the  .fmt  file  directly  and  subsequently 
make  and  save  changes  in  the  forms  design  screen,  your  changes  to 
the  .fmt  file  will  be  overwritten.  To  save  development  time, 
build  the  form  in  the  forms  design  screen.  Then  fine-tune  it  in 
the  program  editor. -ENDBOX- 

One  reason  to  modify  an  .fmt  file  is  to  initialize  memory 
variables  used  in  it.  The  forms  generator  lets  you  place  memory 
variables  (as  well  as  fields)  in  a  form,  but  you  cannot 
initialize  the  variables  within  the  generator.  Instead, 
initialize  the  memory  variables  for  the  screen  form  in  the  setup 
area  of  your  program  file.  Chapter  6,  "The  Main  Program," 
discusses  the  program  setup  area.  See  Chapter  3  for  more  detail 
on  memory  variables. 
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You  might  also  want  to  modify  an  . f mt  file  to  vary  the  location 
of  the  READ  command.  READ  has  two  purposes:  to  activate  GETS 
(which  capture  data  entered  by  the  user)  and  to  insert  a  page 
break.  Editing  the  format  file  directly  gives  you  more  control 
over  these  two  operations. 

Placing  the  READ  at  the  end  of  a  group  of  @. . .SAY. . .GETs  causes 
the  entire  group  to  display  at  once.  The  user  can  backtrack  with 
the  -UA-  or  -PGUP-  key  to  correct  errors.  However,  you  can  also 
step  users  through  screen  prompts  one  at  a  time  by  placing  a  READ 
SAVE  after  each  prompt  except  the  last  one. 

Note  that  you  should  not  end  a  . f mt  file  with  a  READ.  When  you 
put  a  READ  at  the  end  of  a  .  f mt  file,  dBASE  IV  ?.ooks  for  another 
page  of  GETS.  Since  there  are  no  further  SAYs  or  GETS,  the  cursor 
sits  in  the  upper  left  corner  of  the  screen  waiting  for  a  key 
press. 

The  forms  generator  inserts  a  page  break  automatically  after  each 
full  screen  (21  lines).  Therefore,  to  define  a  short  page,  you 
ordinarily  have  to  insert  blank  lines  to  fill  up  the  rest  of  the 
page.  If  you  prefer,  place  a  READ  in  the  . fmt  file  wherever  you 
want  a  page  break  to  appear.  You  can  create  forms  of  up  to  10 
pages . 

Finally,  you  can  control  cursor  movement  on  the  form  with 
modifications  to  the  format  file.  The  order  of  the  GETs  in  the 
format  file  determines  the  order  in  which  the  cursor  advances 
through  the  fields  on  the  form.  In  the  following  example,  the 
order  of  the  GETs  causes  the  cursor  to  skip  over  repetitive 
information  at  the  top  of  the  form.  The  user  only  has  to  enter 
this  information  once;  thereafter,  it  is  carried  forward  by  SET 


-H3~Opening  and  Closing  n  een  Format  Files 

Use  a  format  file  in  a  am  just  as  you  would  at  the  dot 

prompt.  SET  FORMAT  TO  < .  ,,ame>  opens  the  file  in  memory.  dBASE 
IV  first  looks  for  a  compiled  forr  ' . fmo)  file.  If  it  can't 

find  the  .fmo  file,  it  compiles  tl  -mat  (.fmt)  file. 

The  full-screen  commands  APPEND,  EDIT,  CHANGE,  and  READ  display 
the  current  record  in  the  form  for  data  entry  purposes  (see 
"Entering  the  Data  into  the  Database") .  BROWSE  is  also  formatted 
by  the  active  .fmt  file,  but  the  screen  coordinates  have  no 
effect.  CLOSE  FORMAT,  SET  FORMAT  TO  with  no  argument,  and  USE 
with  no  argument  all  close  the  current  format  file.  CLEAR  ALL  and1 
CLOSE  DATABASES  close  all  open  format  files. 

-H2 -GETTING  DATA  WITHOUT  SCREEN  FORMS 
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If  you  have  just  a  few  questions  to  ask  the  user,  you  might  not 
want  to  create  a  screen  form.  Instead,  you  can  build  a  small 
program  file  containing  instructions,  prompts,  and  data  entry 
areas . 

Use  the  TEXT . . . ENDTEXT  command  to  display  blocks  of  text,  and 
?/??  and  @... SAY  to  display  questions,  prompts  and  messages. 
dBASE  paints  the  screen  in  the  order  that  the  @...SAYs  appear  in 
the  file. 

Use  @...GET  and  READ  to  capture  the  user's  responses,  as 
described  under  "Getting  Data  with  Screen  Forms." 

-NOTE- You  can  also  use  ACCEPT,  INPUT,  and  WAIT  to  display  a 
question  and  receive  the  user's  response  in  a  single  step. 
However,  these  commands  have  limited  screen  positioning,  color, 
and  data  validation  capabilities.  For  this  reason,  programmers 
generally  prefer  to  use  the  more  powerful  e. . .SAY. . .GET,  ?,  and 
??  commands.  See  -R- Language  Reference-I-  for  more  information  on 
ACCEPT,  INPUT,  and  WAIT.-ENDBOX- 

-H2 -GETTING  DATA  FROM  AN  ARRAY 

Arrays  are  useful  for  storing  summary  information  in  memory.  Your 
program  can  COPY  data  entered  by  users  to  a  memory  variable 
array,  and  later  read  in  the  data  from  the  array  using  APPEND 
FROM  ARRAY  or  REPLACE.  (See  Chapter  3,  "Memory  Variables,"  for 
more  information  on  memory  variable  arrays.) 

The  following  routine  demonstrates  the  use  of  an  array  to 
calculate  and  print  data.  The  first  segment  determines  how  many 
customers  have  orders  in  the  Orders  database  file.  The  routine 
counts  unique  customer  IDs  by  passing  through  the  database  file 
in  Cust_id  order  and  incrementing  mcount  every  time  the  ID 
changes . 

-NOTE-You  can  omit  this  segment  by  declaring  ar.  array  equal  to 
the  RECCOUNTO  of  the  Customer  database  file.  However,  customer 
records  with  no  orders  will  waste  memory  in  unused  array 
elements.  Since  there  is  a  limit  of  1023  elements  per  array,  the 
maximum  number  of  rows  in  this  2-dimensional  array  cannot  exceed 
511.  As  a  developer  you  must  determine  which  method  is  most 
suitable  for  your  application. -ENDBOX- 

The  second  segment  DECLARES  the  array  subtotals ,  which  is  mcount 
rows  long  by  two  columns  wide.  It  then  loads  the  array  with  the 
customer  ID  in  column  one  and  the  total  bill  in  column  two.  Note 
that  mcount  determines  which  row  to  load. 

The  third  segment  steps  through  the  array  row  by  row  and  prints 
the  results. 

-M-USE  Orders  ORDERS  Cust_id-L- 
mcount  =  1-L- 
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GO  TOP-L- 

mold  =  Cust_id-L- 

SKIP-L- 

SCAN-L- 

mcount  =  mcount  +  IIF(Cust_id  =  mold,  0,  1)~L~ 
mold  =  Cust_id-L- 
ENDSCAN-L- 
\m-L~ 

DECLARE  sub_totals [mcount,  2 l-L- 

GO  TOP-L- 

mold  =  Cust  id-L- 

DO  WHILE  .NOT.  E0F()-L- 

subtotals[mcount, 1]  =  mold-L- 

CALCULATE  SUM(Total_bill)  TO  subtotals [mcount , 2 ] ; ~L~ 

WHILE  Cust_id  =  mold-L- 
mcount  =  mcount  +  1-L- 
mold  =  Cust_id-L- 
ENDDO-L- 
\m-L- 

most_count  =  mcount-L- 
mcount  =  1-L- 

DO  WHILE  mcount  <=  most_count-L~ 

?  subtotals [mcount, 1]  AT  10,  subtotals [mcount, 2]  AT  20-L- 
mcount  =  mcount  +  1-L- 
ENDDO-L— N- 

-H2 '-FORMATTING  DATA  ENTRY  SCREENS 

Your  application  will  look  more  professional  if  you  format  the 
SAY  prompts  and  GET  data  input  areas.  This  section  discusses  how 
to  format  the  SAYs  and  GETs  themselves.  See  "Formatting  Data"  for 
information  on  how  to  format  the  information  that  the  user 
enters . 

~H3~Setting  Intensity,  Delimiters,  and  Color 

You  can  control  the  intensity  of  GET  fields,  the  character  used 
to  delimit  them,  and  the  color  of  both  SAYs  and  GETS. 

SET  INTENSITY  ON,  the  default,  displays  SAYs  in  standard  mode  and 
GETs  in  enhanced  mode  (inverse  video) .  SET  INTENSITY  OFF  uses 
standard  mode  for  both.  You  can  also  SET  DELIMITERS  to  specify  a 
character  string  to  delimit  the  GETs. 

You  can  control  the  colors  of  the  SAYs  and  GETS  with  either  SET 
COLOR  or  the  COLOR  option  of  the  @  command.  See  Language 
Reference  for  a  table  of  SET  COLOR  values.  Chapter  6,  "The  Look 
of  Your  Application,"  discusses  color  in  more  detail. 

This  example  displays  the  SAYs  in  blue  against  a  white  background 
and  the  GETs  in  yellow  against  a  red  background,  with  the  GETs 
enhanced  and  delimited  by  curly  braces. 

-M-SET  COLOR  TO  B/W,GR+/R~L~ 
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SET  INTENSITY  ON-L- 
SET  DELIMITERS  TO  "()"-L- 
SET  DELIMITERS  ON-N- 

-H3-Displaying  a  Memo  Field  in  a  Window 

The  WINDOW  option  of  the  @. . .SAY. . .GET  command  lets  you  display  a 
memo  field  in  a  window.  Ii  you  OPEN  WINDOW,  the  contents  of  the 
memo  field  are  visible.  Without  the  OPEN  keyword,  the  window  is 
closed  and  the  field  displays  with  the  standard  memo  icon. 

This  example  defines  a  screen  form  with  an  open  memo  window: 

-M-USE  Goods  ORDER  Part_id-L- 

DEFINE  WINDOW  memo_win  FROM  19,22  TO  22,79-L- 

DO  Screen-L- 

\m-L- 

PROCEDURE  Screen-L- 

*  ...  &&  @ .. .SAY. . .GETS  outside  the  memo  window-L- 
@  19,  9  SAY  "DESCRIPTION:  "  GET  Descrip  OPEN  WINDOW  memo  win-L- 
RETURN-N- 


-H2 -CUSTOMIZING  BROWSE  TABLES 

The  options  of  the  BROWSE  command  provide  a  lot  of  flexibility  in 
formatting  a  Browse  table.  See  the  discussion  of  this  command  in 
Language  Reference  for  a  complete  description  of  its  many 
options.  Table  9-1  gives  a  brief  overview. 


-TABLE-Table  9-l\mBR0WSE  command  options 


Option  Purpose 


COMPRESS 

FIELDS 

FORMAT 

FREEZE 

LOCK 

NOAPPEND 

NOCLEAR 

NODELETE 

NOEDIT 

NOFOLLOW 

NOTNIT 

NOMENU 

WIDTH 

WINDOW 


Compress  table  vertically  to  allow  two  more  rows 
Specify  which  fields  display,  and  in  what  order 
Activate  current  screen  format  f ile-SUP-l-DN- 
Confine  the  cursor  to  a  specific  column 
Keep  lefthand  columns  on  the  screen  when  panning 
Prevent  addition  of  records 

Keep  table  on  screen  when  user  exits  BROWSE-SUP-2- 
Prevent  deletion  of  records 
Prevent  editing  of  records 

Keep  cursor  from  following  edited  key  field-SUP-3-DN- 
Re-use  previously  defined  Browse  table 
Prevent  access  to  the  Browse  menu  bar 
Specify  width  for  columns 
Display  Browse  table  in  a  window 


Notes: 

1.  Any  attributes  defined  in  the  current  format  file,  such  as 
PICTURE  and  VALID,  are  effective  in  the  Browse  table  as  well  as 
the  form. 
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2.  dBASE  IV  releases  the  allocated  memory  when  the  database  file 
is  closed. 

3.  If  adding  a  record  or  editing  the  key  field  repositions  that 
field  in  the  index  file,  the  cursor  follows  the  repositioned 
field  by  default.  The  NOFOLLOW  option  prevents  this  from 
happening.  Instead,  the  record  that  replaces  the  repositioned  one 
in  the  index  file  becomes  the  new  current  record. -ENDTABLE- 

Figure  9-2  shows  a  Browse  table  in  a  window.  The  FORMAT  option  ir 
the  BROWSE  command  activates  the  current  format  file,  Brow  fmt, 
so  PICTURE  functions  and  data  validation  options  operate  during 
the  Browse.  The  NOAPPEND,  NOEDIT,  NODELETE,  and  NOMENU  options 
make  this  table  read-only,  to  simulate  a  Rolodex-TM-  file  that 
the  user  cannot  edit. 

-ILLUS-Figure  9-2\mBrowse  table  with  code 


-M-USE  Vendors  ORDER  Vendor  id-L- 

DEFINE  WINDOW  browse  win  FR0M  1,5  TO  20,70  COLOR  G/W-L- 
CLEAR-L- 

SET  FORMAT  TO  Brow_fmt-L- 

BROWSE  FIELDS  Vendor , Phone_vend , Contact_v  FORMAT  NOEDIT  ;-L- 
NODELETE  NOAPPEND  NOMENU  COMPRESS  WINDOW  browse_win-N— ENDFIG- 

-H2-FORMATTING  DATA 

Data  in  its  raw  state  is  unformatted.  There  are  no  commas  or 
dollar  signs  in  numeric  fields,  and  date  fields  all  appear  in  a 
single,  default  format.  The  @. . .SAY. . .GET  and  ?/??  commands  have 
special  formatting  options  called  PICTURES  and  FUNCTIONS.  You  cai 
use  these  options,  for  example,  to: 

-o-Enter  characters  for  the  user,  such  as  the  parentheses  and 
hyphen  in  American  phone  numbers 

-o-Display  numbers  in  the  currency  format  of  various  countries 
-o-Display  dates  in  American  or  international  format 
-o-Force  upper  case 

-o-Limit  entry  in  a  character  field  to'  numbers  or 
letters-ENDLIST- 

PICTURE  templates  format  characters  individually,  while  FUNCTION: 
format  the  entire  variable.  To  combine  PICTURES  and  FUNCTIONS, 
use  the  syntax  PICTURE  "8<function>  <template>"  (see  examples 
below) .  These  options  are  described  in  detail  in  Language 
Reference. 

Table  9-2  shows  some  useful  PICTURE  and  FUNCTION  clauses. 
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TABLE-Table  9-2\mCommonly  used  PICTURES  and  FUNCTIONS 


Example 


Results  in 


@ . . . SAY  "Phone:  "  GET  Phone; 

PICTURE  "(999)999-9999" 

@...SAY  "SSN:  "  GET  SSN; 

PICTURE  "999-99-9999" 

?  subtotal  AT  10  PICTURE; 

"9,999,999.99" 

S...GET  Address  PICTURE; 

"XXXXXXXXXXXXXXXXXXXXXXXXX" 

@...GET  Date  PICTURE  "@D" 

@ . .  . SAY  "Choose  A-G  or  X  to  exit"; 

GET  choice  PICTURE  "!" 

@ .  .  • SAY  "Is  this  correct?  (Y/N)"; 

GET  Manswer  PICTURE  "Y" 

?  mamount  AT  10  FUNCTION  "@L$" 

??  mamount  AT  10  FUNCTION  "XC$" 

?  mdate  AT  10  FUNCTION  "@E" 

§...GET  " Codename " ; 

PICTURE  "@R  X  X  X  X  X  X" 

@ .  .  . SAY  "Enter  last  name:"  GET  mlast; 

PICTURE  "@S7  !  AAAAAAAAAAAAAAAAAAA" 
@...SAY  "Day  of  week"  GET  Day; 

PICTURE  " @M  Mon, Tues, Wed,Thu, Fri" 


(818) 555-1234 

555-76-2616 

1,234,567.89 

1234  Birth  St. 

09/12/87-SUP-l-DN- 

C 

Y  or  N 

$000,123,456. 78-SUP-2-DN- 
$1,234.56  DB 
$3,456.78  CR 
12/09/87 

S  H  A  D  0  W-SUP-3-DN- 
Beethov-SUP- 4  -  DN- 
Mon 


TT  This  format  does  not  validate  the  user's  entry.  dBASE  IV  will 
validate  the  user's  date  entries  for  you  if  you  define  the  GET 
memory  variable  as  a  date  type:  Date  =  {  /  /  ) 

2.  The  L  function  causes  leading  zeroes  to  display. 

3.  The  R  function  tells  dBASE  IV  to  display  the  non-template 
characters  (here,  the  spaces) ,  but  not  to  store  them  in  the  GET 
variable. 

4.  The  @S7  function  causes  the  entry  to  scroll  in  a  /-character 
window.  Thus,  the  en  of  Beethoven  is  initially  out  of 

view. -ENDTABLE- 


In  the  following  example,  the  !  FUNCTION  displays  the  last  name 
in  upper-case  letters,  while  the  !  PICTURE  template  formats  the 
first  name  with  an  initial  capital  letter.  The  A  PICTURE  template 
allows  the  user  to  enter  only  letters  in  the  Firstname  field. 

The  SSN  (social  security  number)  PICTURE  template  enters  hyphens 
for  the  user.  The  Rate  field  is  formatted  by  a  combined  function 
and  template.  The  $  function  produces  currency  format,  while  the 
template  symbols  limit  the  number  of  digits  and  enter  the  decimal 
point  for  the  user. 

Finally,  Pay_hist  is  an  enumerated  data  option.  The  Excelnt 
option  will  appear  by  default. 

-M~@ . . . SAY  "Last  name:  "  GET  Lastname  FUNCTION  "!"~L~ 
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@...SAY  "First  name:  "  GET  Firstnnme:-L- 
PICTURE  "!  AAAAAAAAAAAAA"-L- 

@...SAY  "Social  security  no:  "  GET  SSN  PICTURE  "999-99-9999.1..  r_ 

@  •  .  . SAY  "Billing  rate:  "  GET  Rate  PICTURE  "@$  999.99"-L- 
@ .  .  . SAY  "Payment  history:  "  GET  Pay  hist;-L- 
PICTURE  " @M  Excelnt , Good, Fair , Poor" ; -L- 
MESSAGE  "SPACEBAR  to  scroll,  RETURN  to  select. "-N- 

-TIP-You  can  initialize  a  memory  variable  with  a  PICTURE  clause 
and  then  @. . .SAY. . .GET  the  variable.  For  example: 

-M-money  =  "§$  999 , 999 . 99"-L- 
@ . . . SAY  amount  PICTURE  money-N- 

Using  this  method  instead  of  macro  substitution  will  reduce  your 
program's  execution  time . -ENr^^X- 

-H2-CHECKING  DATA  FOR  ERRORS 

Your  program  should  evaluate  data  entered  by  the  user  before 
writing  it  to  the  database  file.  This  helps  to  ensure  the 
integrity  of  the  database.  Using  data  validation  routines,  your 
program  can  check  data: 

-o-Against  a  range 

-o-Against  conditions 

-o-Against  a  list 

-o-Against  a  database  file 

-o-For  duplication-ENDLIST- 

-H3 -Checking  Against  a  Range 

The  @. . .SAY. . .GET  RANGF  ion  sets  lower  and  upper  boundaries  on 
numbers  and  dates  ente  users. 

-M-date_var  =  { )  &&  Ini  izes  a  null  date  variable-L- 
date_low  =  { 04/01/89 }~L~ 
date_high  =  { 04/30/89 }-L~ 

@...GET  date_var  RANGE  date_low,c  ^gh-N- 

You  can  restrict  the  lower  or  upper  boundary  alone,  by  omitting 
one  of  the  parameters.  (Don't  omit  the  comma.)  If  the  user's 
entry  is  out  of  range,  dBASE  IV  shows  the  proper  range  on  the 
status  line  and  instructs  the  user  to  press  -SPACEBAR-  to 
continue. 

-H3-Checking  Against  Conditions 

Two  options  of  the  @. . .SAY. . .GET  command,  VALID  and  WHEN,  let  you 
specify  conditions  for  data  entry. 
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-H4-Using  @. .  .SAY.  .  .GET  VALID 

The  VALID  option  of  the  @. . .SAY. . .GET  command  lets  you  reject 
data  entered  by  the  user  if  it  doesn't  meet  the  conditions  you 
specify.  You  will  find  many  uses  for  this  post-processing 
capability.  For  example,  you  can  use  it  to  check  for  forbidden 
characters. 

Suppose  you  want  to  obtain  a  Yes/No  response  to  the  question 
"Begin  printing?".  The  VALID  condition  and  the  !  function  in  the 
following  module  ensure  that  the  character  entered  into  answer  is 
either  Y,  N,  y,  or  n.  The  program  rejects  any  other  character  and 
displays  an  error  message. 

-M-answer  =  ""-L~ 

@...SAY  "Begin  printing?  (Y/N) "  GET  answer  FUNCTION  "!";-L- 
VALID  answer  $  "YN"  ;~L~ 

ERROR  "Enter  Y  or  N."-L- 
READ-N- 

The  previous  example  identified  the  allowed  characters.  If  you 
want  to  allow  many  characters  and  exclude  only  a  few,  it  is 
sometimes  more  efficient  to  identify  the  forbidden  characters. 

For  example,  suppose  part  numbers  beginning  with  the  letters  X, 

Y,  or  Z  have  been  discontinued.  The  following  code  prevents  users 
from  enterinq  one  of  these  part  numbers: 

~M~mpart_id  =  SPACE(10)-L- 
discont  =  "XYZ"~L~ 

CLEAR- L~ 

@ , SAY  "Enter  part  no.:  "  GET  mpart_id  PICTURE  "!-###-####"  ;-L- 
VALID  .NOT.  LEFT(mpart_id, 1)  $  discont  ;-L~ 

ERROR  "Discontinued  part  number. "-L- 
READ-N- 

To  exclude  spaces  in  the  part  numbers,  you  would  initialize  a 
memory  variable,  mspace  =  *  ”,  and  modify  the  VALID  clause  to 
read  VALID  .NOT.  SUBSTR (mpartid ,1,10)  $  mspace. 

In  the  next  routine,  the  VALID  expression  contains  an  immediate 
IF  statement.  The  IIF()  accepts  the  user's  entry  only  if  the  part 
number  is  in  the  file  and  the  quantity  ordered  is  less  than  or 
equal  to  the  quantity  on  hand.  Otherwise,  an  error  message 
appears  on  the  screen. 

-M-USE  Orders  ORDER  Part  id-L- 
USE  Goods  ORDER  Part_id  TN  2-L- 
mpart  id  =  SPACE (4) -L- 
m quantity  =  0-L- 

@  5,10  SAY  "Enter  part  no.:  "  GET  mpart_id  PICTURE  "!999"-L~ 
i  6,10  SAY  "Enter  order  quantity:  "  GET  mquantity  FUNCTION  "9" 
;-L~ 

VALID  IIF (SEEK(mpart_id,  Goods)  .AND.  ; 
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mquantity  <=  Goods->Quantity , .T. , . F. ) -L- 

ERROR  "Incorrect  part  number  or  insufficient  stock  on  hand."-L~ 
READ-N- 

Examples  under  "Checking  for  Duplicate  Key  Fields,"  "Checking 
Against  a  List,"  and  "Checking  Against  a  Database  File"  show  the 
use  of  VALID  with  a  user-defined  function. 

-H4 -Using  .  .SAY. .  .GET  WHEN 

The  more  global  WHEN  option  controls  whether  users  may  edit  a 
field  at  all  (also  known  as  pre-processing) .  The  following 
routine  forces  users  to  fill  in  a  part  number  before  entering  a 
part  name.  The  WHEN  condition  evaluates  the  contents  of  the 
Part_id  field  to  ensure  that  it  is  not  empty  (null) .  If  it  is, 
the  cursor  skips  over  the  Part  Name  option  when  the  user  tries  to 
edit  it. 

-M-@ . . . SAY  "Enter  part  number:  "  GET  Part_id-L- 
@  ..SAY  "Part  name:  "  GET  Part  name-L- 
WHEN  ""  <>  TRIM(Part_id) ;~L~ 

READ-N- 

~H3~Checking  Against  a  List 

Your  program  can  check  user  entries  against  an  approved  list.  In 
the  following  routine,  the  main  program  defines  two  lists,  one 
for  items  slightly  marked  down  and  another  for  items  being  sold 
at  cost.  Then  it  prompts  the  user  for  a  part  number. 

The  VALID  clause  activates  the  Lookupid  user-defined  function. 
This  UDF  uses  LEFT( )  to  identify  the  first  character  of  the 
user's  entry,  and  then  checks  the  appropriate  list  or  file.  If  it 
doesn't  find  the  part  number,  it  runs  the  Not_found  procedure. 

Not_found  uses  a  CASE  statement  to  assign  a  message  appropriate 
to  each  list.  Then  it  displays  the  message  in  one  window  and  the 
proper  parts  list  in  another.  (This  example  assumes  that  the 
windows  have  already  been  defined.) 

-M-markdown  =  "M100,M200,M250,M350,M425,M500,M600,M750,M900"-L- 
at_cost  =  "C100,C155,C175,C195,C200,C205,C220,C260,C300,C355"-L- 
mpart_id  =  SPACE ( 4 ) -L~ 

USE  Goods  ORDER  Part_id-L- 

@  5,10  SAY  "Enter  part  number:  "  GET  mpart_id  PICTURE  "!999"  ;-L- 
VALID  Lookupid(mpart_id)  ;-L~ 

MESSAGE  "Enter  part  number,  for  example,  A250"  ;-L- 
ERROR  "Incorrect  part  number.  Press  spacebar  and  revise. "-L- 
READ-L- 
\m~  L- 

FUNCTION  Lookupid-L- 
PARAMETERS  entry-L- 
is_here  =  . T.-L- 
DO  CASE-L- 
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CASE  entry  =  "M"  .AND.  .NOT.  entry  S  markdown- L~ 

DO  Notfound  WITH  "markdown"-L- 
CASE  entry  ="C"  .AND.  .NOT.  entry  $  at  coat-L- 
DO  Not  found  WITH  "at  cost"-L~ 

ENDCASE-L-  ~ 

RETURN ( is_here) ~L~ 

\m~L~ 

PROCEDURE  Not_found-L~ 

PARAMETERS  this_list-L- 

message  =  "Part  number  not  in  "  +  this  list  +  "list." 
is_here  =  . F.-L- 
answer  =  "  "-L- 

ACTIVATE  WINDOW  alert_win-L~ 

@  1,0  SAY  message- L~ 

WAIT  "Press  S  to  stop  or  spacebar  to  see  parts  list."  ;-L- 
TO  answer-L- 

DEACTIVATE  WINDOW  alert  win-L- 

ACTIVATE  WINDOW  look  wiii-L- 

SCAN  ALL  WHILE  UPPERTanswer )  <>  "S"-L- 

@1,1  SAY  "Part  No.  Part  Name"  SSAssumes  HEADING  OFF-L- 

LIST  Part_id  +  SPACE (3)  +  Part_name  NEXT  10-L- 

WAIT  "Press  spacebar  to  continue  or  S  to  stop."  ;~L~ 

TO  answer-L- 
CLEAR-L- 
ENDSCAN-L- 

DEACTIVATE  WINDOW  look_win-L- 
RETURN-N- 

-H3-Checking  Against  a  Database  File 

A  program  can  check  user  entries  against  a  database  file.  The 
routine  below  checks  whether  the  part  number  entered  by  the  user 
is  in  the  Goods  database  file.  The  Lookupid  UDF  sets  is  here  to 
false  if  the  SEEK ( )  fails  to  find  the  part  number.  Then  it 
displays  valid  part  numbers  in  a  window,  ten  at  a  time,  until  the 
user  presses  S  to  stop  tho  listing.  Finally,  the  @. . .SAY. . .ERROR 
clause  prompts  the  user  to  enter  the  correct  part  number. 

-M-USE  Orders  ORDER  Part  id-L- 
USE  Goods  ORDER  Part  id  TN  2-L- 
DEFINE  WINDOW  look  win  FROM  6,10  TO  22,65-L- 
mpartid  =  SPACE (4j-L- 

@  5,10  SAY  "Enter  part  number:  "  GET  mpart_id  PICTURE  "!999"  ;-L~ 
VALID  Lookupid (mpart_id)  ;-L~ 

ERROR  "Please  enter  correct  part  number  noted  earlier . "-L- 
READ-L- 
\m-L- 

FUNCTION  Lookupid-L- 
PARAMETERS  entry-L- 

ishere  =  IIF (SEEK (entry , "Goods") , .T. F. ) -L- 
IF  .NOT.  ishere-L- 
SELECT  2-L- 

ACTIVATE  WINDOW  look_win-L~ 
answer  =  ""~L~ 
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GO  TOP-L- 

SCAN  WHILE  UPPER  (answer)  <>  "S"-L- 

LIST  NEXT  10  Part  id.  Part  name-L- 
?-L- 

?  "Invalid  part  no.  Please  note  correct  no.  in  list."-L~ 
WAIT  "Press  S  to  stop,  any  other  key  to  continue."  ; 

TO  answer-L- 
CLEAR-L- 
ENDSCAN-L- 

DEACTIVATE  WINDOW  look  win-L- 
SELECT  1-L- 
ENDIF-L- 

RETURN ( is_here) -N- 
-H3-Checking  for  Duplication 

Your  program  can  check  for  duplicate  key  fields  or  duplicate 
characters  in  any  field. 

Suppose  an  application  lets  users  choose  the  options  "Add  record" 
or  "Edit  record"  from  a  menu,  and  then  enter  data.  The  next 
routine  checks  the  data  entered  by  the  user  for  a  duplicate  part 
number.  The  VALID  clause  calls  the  user-defined  function  Chk_dup, 
which  first  stores  the  record  number  of  the  new  or  edited  record, 
and  then  seeks  a  matching  part  number  in  the  file. 

The  IIF()  statement  sets  rec_uniq  to  .F.  whenever  a  different 
record  (one  with  a  diffurent  record  number)  with  the  same  key 
field  is  found  in  the  database  file.  This  error  could  occur 
whether  the  user  is  editing  (PROMPT ()  =  "Edit  record")  or  adding 
data. 

The  only  allowed  case  cf  duplication  occurs  when  the  record 
numbers  are  the  same  and  the  value  of  PR0MPT()  is  "Edit  record." 
Here,  the  user  is  simply  editing  a  record,  and  the  SEEK ( )  has 
stopped  at  the  original  version  of  the  record  being  edited. 

The  value  of  recjiniq  is  RETURNed  to  the  VALID  clause.  If 
rec  uniq  is  .F.,  the  UDF  displays  the  message  Duplicate  part 
numBers  not  allowed. 

-M-USE  Goods  ORDER  Part_id~L~ 
mpart_id  =  SPACE (4) -L- 

@ . . . SAY  "Enter  part  no.:  "  GET  mpart_id  PICTURE  "!999"  ;-L~ 

VALID  Chk  dup(mpart  id)-L- 
\m-L~ 

FUNCTION  Chk  dup-L- 
PARAMETERS  entry-L- 
rec_uniq  =  . T . - L- 
record  =  RECNO()-L- 
IF  SEEK (entry) -L- 

rec  uniq  =  IIF( record  =  RECNO()  .AND.  ;~L~ 

PROMPT ()  =  "Edit  record", .T.,.F.)~L~ 

ENDIF-L- 
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IF  .NOT.  rec  unique-L- 

DO  Msg  WITH  CHR(7)  +  "Duplicate  part  numbers  not  allowed. "-L- 
ENDIF-L- 
GO  record-L- 
RETURN(rec_uniq) -N- 

A  program  can  also  check  for  duplicate  characters  in  a  string. 

For  example,  the  LIKE ( )  function  can  ensure  that  the  first 
character  in  mvend_id  is  always  a  5,  and  that  the  5  is  not 
duplicated  elsewhere  in  the  field: 

-M-IF  mvend_id  =  "5"  .AND.  .NOT.  LIKE ( "5*5*" ,mvend_id) ~L~ 

?  "First  and  only  first  digit  must  be  a  5"-L- 
ENDIF-N- 

-H2 -PROCESSING  KEYPRESSES 

The  INKEY ( ) ,  LASTKEY ( ) ,  and  READKEY ( )  functions  allow  your 
application  to  do  selective  processing  depending  on  what  keys  a 
user  has  pressed.  Table  9-3  summarizes  the  differences  between 
these  three  functions.  (See  Language  Reference  for  tables  of  the 
actual  codes  that  dBASE  IV  returns  for  each  keypress.) 

-TABLE-Table  9-3\mDif ferences  between  INKEY (),  LASTKEY ( ) ,  and 
READKEY ( ) 

Function 

INKEY ( ) 


-SUP-l-DN- 
READKEY ( ) 


LASTKEY ( ) 


Notes: 

1.  INKEY (0)  pauses  the  program  until  the  user  presses  a  key. 
INKEY (n)  pauses  the  program  the  designated  length  of  time. 

2.  READKEY ()  returns  one  of  two  possible  codes:  a  number  from  0 
to  36  if  no  data  was  changed  prior  to  exit,  and  that  number 
increased  by  256  if  data  was  changed. -ENDTABLE- 

Notice  the  relationship  between  READKEY ()  and  LASTKEY ( ) . 

READKEY ()  determines  whether  the  user  saved  data  or  discarded 
changes  when  exiting  a  full-screen  command.  LASTKEY ()  then 
determines  precisely  what  key  the  user  pressed  to  exit. 


Returns 


Use 


ASCII  code  of  current  keypress 
(first  key  in  type-ahead  buffer) 


With  menus  and 
prompts  or  to 
pause  program 


dBASE  code  of  key  pressed  to 
exit  full-screen  command- SUP- 2- DN- 


ASCJI  code  of  key  used  to  exit 
full-screen  command 


With  full-screen 
commands  or 
@ . . . GETS 

with  full-screen 
commands  or 
@ . . . GETS 
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The  first  routine  below  lets  the  user  press  -F10-  to  access  a 
help  screen  or  -RETURN-  to  edit  data.  Assume  the  existence  of  a 
help  procedure  called  Helper.  The  INKEY (0)  causes  the  program  to 
wait  until  the  user  presses  a  key. 


-M-CLEAR-L- 

mpart_id  =  SPACE (4) -L- 

@ . . . SAY  "Press  F10  for  help  or  RETURN  to  enter  data."-L- 
keypress  =  INKEY (0)-L~ 

DO  CASE  -L- 

CASE  keypress  =  15-L- 

*  <data  entry  commands>-L~ 

CASE  keypress  =  -9-L- 
DO  Helper- Ij- 
ENDCASE-N- 

The  next  routine  uses  a  Load_rec  procedure  to  copy  the  data  from 
record  5  into  memory  variables.  Another  procedure,  Editrec,  lets 
the  user  edit  the  data.  If  the  user  presses  -RETURN-  (READKEY ( )  = 

270)  or  -CONTROL - END-  (READKEY ( )  =  271),  Sav_data  REPLACES  the 

data  in  ths  database  file. 

-M-USE  Goods-L- 
G0  5-L- 

D0  Load_nc-L~ 

DO  Edit_rec-L- 
IF  READKEY ()  >  255-L- 
DO  Sav_data~L~ 

ENDIF-N- 

-H2-HELPING  THE  USER 

User  help  in  a  dBASE  I"  application  can  vary  from  simple  to 
sophisticated.  Options  of  the  @ . . . SAY . . . GET  command  display 
one-line  help  prompts.  You  can  also  create  a  help  text  file  that 
users  can  call  from  the  program.  Finally,  you  can  design  a 
context-sensitive  help  system,  so  that  users  can  obtain  help 
relevant  to  the  tasks  they  are  doing. 

-H3 -Providing  Help  with  0. . .SAY. . .GET 

Options  of  the  @.  .  .SAY. . .GET  command  can  accomplish  many  simple 
user  help  functions  in  your  program.  The  PICTURE  and  FUNCTION 
options  force  user  entries  into  a  required  format  (see 
"Formatting  Data"  above) .  The  RANGE  option  automatically  displays 
an  error  message  if  the  user's  entry  is  out  of  range.  The  ERROR 
clause  of  the  VALID  option  displays  a  message  of  up  to  80 
characters  if  the  user's  entry  fails  the  VALID  (see  "Using 
@. . .SAY. . .GET  VALID") . 

-H3~Providing  a  Help  Text  File 
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To  provide  extensive  help  text,  create  a  help  file  using  the 
TEXT . . . ENDTEXT  construct.  If  the  help  file  is  used  by  only  one 
program,  include  it  as  a  procedure  within  that  program.  However, 
if  several  programs  use  the  same  help  text,  create  a  separate 
Help.prg  file.  Have  each  program  DO  this  external  help  file  as 
needed.  This  approach  saves  many  lines  of  code,  by  not  repeating 
the  help  procedure  throughout  your  application. 

The  basic  format  for  a  help  file  is: 

-M-CLEAR-L- 
@  0,0-L- 
TEXT-L- 

.  &&  Help  text.  Format  the  text  exactly  as  you  want  it-L- 
.  &&  to  appear  on  the  screen:  you  must  supply-L- 
.  &&  indentation,  underlining,  and  so  on.-L- 
ENDTEXT-L- 

WAIT  "End  of  help  file.  Press  any  key  to  continue . "-L- 

CLEAR-L- 

RETURN-N- 

-H3-Providing  Context-Sensitive  Help 

The  core  of  a  dBASE  IV  context  sensitive  help  routine  is  the 
READVAR()  function.  READVAR ( )  returns  an  uppercase  text  string 
containing  tne  name  of  the  field  or  memory  variable  currently 
being  altered.  You  can  use  READVAR ( )  with  ON  KEY  to  develop  a 
single  procedure  providing  help  for  all  GETS  in  a  form. 


-M-ON  KEY  FI  DO  Get_help~L~ 

CLEAR- L- 

@  10,10  SAY  "Name  "  GET  Name-L- 

@  12,10  SAY  "City  "  GET  City-L- 

@  14,10  SAY  "State  "  GET  State-L- 

@  22,30  SAY  "Press  FI  for  help"-L~ 

READ-L- 
ON  KEY-L- 
RETURN-L- 
-L~ 

PROCEDURE  Get  help-L- 
null  =  INKEY (T-L- 

DEF1NE  WINDOW  Get_win  FROM  16,10  TO  20,60-L- 
ACTIVATE  WINDOW  Get_win~L~ 

DO  CASE-L- 

CASE  READVAR ()  =  "NAME"-L- 
TEXT-L- 

The  name  can  be  the  first  or  last  nar.e  of-L- 
the  patient.  The  name  can  be  found  on  line  2-L- 
of  form  1070. -L- 
ENDTEXT-L- 
OTHERWISE'LL"* 

??  "Sorry,  there  is  no  additional  information”-L- 
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?  "about  " , READVAR ( ) , " . "-L- 
ENDCASE-L- 

WAIT  "Press  any  key  when  done  with  Help"  TO  null-L- 
DEACTIVATE  WINDOW  Get_win-L- 
RELEASE  WINDOW  Get_win-L~ 

RETURN-N- 

-H2 -ENTERING  THE  DATA  INTO  THE  DATABASE 

You  use  the  same  commands  for  data  entry  in  your  programs  as  you 
use  at  the  dot  prompt:  APPEND,  EDIT,  CHANGE,  and  REPLACE.  This 
section  shows  two  basic  approaches  for  entering  data  into  the 
database. 

-H3-Using  APPEND,  EDIT,  and  CHANGE 

APPEND,  EDIT,  and  CHANGE  display  the  database  in  form  view.  A 
single  record  appears  according  to  a  designated  screen  format 
file.  Using  these  commands  in  a  program  to  enter  data  into  the 
database  is  quite  straightforward.  You  just  create  the  screen 
format  file,  activate  it  with  SET  FORMAT,  and  then  issue  the 
desired  editing  command. 

To  let  the  user  add  one  record  at  a  time,  display  a  data  entry 
form  to  capture  and  validate  the  data  (see  "Getting  Data  with 
Screen  Forms"  and  "Checking  Data  for  Errors"  above) .  Then  APPEND 
BLANK  to  display  a  blank  record,  and  have  the  user  EDIT  that 
record. 

-M-SET  FORMAT  TO  Invoice-L- 
APPEND  BLANK- L~ 

EDIT  NEXT  1-N- 

Here's  how  to  permit  editing  of  a  single  record.  (The  example 
assumes  that  the  user  has  already  entered  the  search  string, 
string ) : 

-M-SET  FORMAT  TO  c.fmt  filename>-L- 
SEEK  string-L- 
IF  FOUND  ()-L- 

EDIT  NEXT  1-L- 
ENDIF-N- 

Use  a  FILTER  condition  to  let  users  EDIT  or  CHANGE  an  unspecified 
number  of  records  without  granting  access  to  other  records.  The 
routine  below  lets  the  user  edit  records  for  a  selected  vendor. 
First,  the  @. . .SAY. . .GET  and  READ  commands  capture  the  user's 
entry  of  a  vendor  number.  If  the  user  presses  -ESC-  (ASCII  code 
27) ,  the  routine  EXITS  at  this  point.  Otherwise,  the  routine 
FILTERS  the  Goods  database  file  by  the  specified  vendor  number. 
Finally,  if  any  records  match  the  FILTER  condition,  the  EDIT 
command  shows  the  first  matching  record. 

-M-USE  Goods  ORDER  Vendor  id-L- 
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DO  WHILE  .T.-L- 

mvendor_id  =  SPACE  (4).-L- 
CLEAR-L- 

@ . . . SAY  "Enter  vendor  number,  or  press  Esc  to  exit.";-L- 
GET  mvendor  id  PICTURE  " '999"-L~ 

READ-L- 

IF  LASTKEY ( )  =  27 
EXIT-L- 
ENDIF-L- 

SET  FILTER  TO  Vendor  id  =  mvendor  id- L~ 

SKIP-L- 
GO  TOP-L- 
IF  .NOT.  EOF ( ) -L- 
EDIT-L- 
ELSE-L- 

??  CHR(7)-L- 

@  15,30  SAY  "Vendor  ID  not  found.  Please  try  again. "-L- 
ENDIF-L- 
ENDDO-N- 

In  both  these  examples,  you  can  use  CHANGE  in  place  of  EDIT.  EDIT 
and  CHANGE  have  several  other  useful  options.  These  options  are 
the  same  as  those  provided  with  BROWSE.  See  Table  9-2  earlier  in 
this  chapter  for  a  summary. 

-H3 -Using  REPLACE 

For  maximum  database  integrity,  REPLACE  the  data  into  the 
database  file.  This  method  stores  the  information  that  the  user 
enters  in  memory  variables.  After  verifying  that  the  data  is 
correct,  the  program  REPLACES  the  old  data  with  the  new  or 
revised  data.  The  end-user  never  touches  the  data  in  the  database 
file. 

-NOTE-You  should  always  use  the  REPLACE  method  if  you  intend  to 
run  your  application  on  a  network.  Working  with  memory  variables 
rather  than  the  records  themselves  minimizes  the  amount  of  time  a 
record  is  inaccessible  due  to  an  RLOCK() . -ENDBOX- 

For  the  following  routine,  assume  that  mvendor_id,  mpart  id, 
mdescrip,  and  mcost  have  already  been  declared.  The  routine  first 
activates  a  format  file,  Inv  mem.  Then  it  DOes  the  Init_fld 
procedure,  which  fills  the  GETS  in  the  format  file  with  blanks. 

If  the  user  enters  a  vendor  number,  the  immediate  IF  command 
APPENDS  a  BLANK  record  and  REPLACES  the  blanked  fields  with  the 
data  entered  by  the  user.  Otherwise,  the  IIF()  sets  blankdata  to 
•  T.,  which  causes  an  EXIT. 

-M-USE  Goods-L- 
SET  FORMAT  TO  Inv_mem~L~ 
blankdata  =  . F.-L- 
DO  Init  fld-L- 
DO  WHILE  .NOT.  blankdata-L- 
READ-L- 
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blankdata  =  IIF(""  =  TRIM(mvendor  id) , .T. , . F . ) ~L~ 

IF  .NOT.  blankdata-L- 
APPEND  BLANK- L- 

REPLACE  Vendor_id  WITH  mvendor_id,  Part_id  WITH  ;-L- 
mpart_id.  Descrip  WITH  mdescrip.  Cost  WITH  mcost-L- 
DO  Init_f ld-L- 
ELSE-L- 

EXIT-L- 

ENDIF-L- 

ENDDO-N- 

You  can  use  a  similar  approach  to  edit  existing  records.  This 
example  updates  the  salaries  of  employees  who  have  received  a 
raise: 

-M-USE  Employee-L- 
title  =  SPACE ( 15) -L- 
raise  =  0.0-L- 
CLEAR- L- 

@  12,10  SAY  "Enter  employee  title:  "  GET  title-L- 
@  14,10  SAY  "Enter  percent  of  raise:  "  GET  raise  ;-L- 
PICTURE  "99 . 9"-L- 
READ-L- 

REPLACE  ALL  Salary  WITH  Salary  *  (l+(raise/100) )  ;-L- 
FOR  Title  =  title-N- 

Variation  #1  —  Carrying  Data  Forward 

The  SET  CARRY  command  lets  you  carry  forward  the  contents  of  one 
or  more  fields  in  a  database  file  when  APPENDing  data.  (Memory 
variables  always  carry  forward  unless  your  program  changes  their 
contents.)  SET  CARRY  affects  screen  format  files,  and  the 
full-screen  commands  AI PEND',  BROWSE,  EDIT,  and  CHANGE. 

You  can  save  the  user  unnecessary  keystrokes  by  carrying  forward 
specific  fields.  In  the  following  example,  the  State  field  will 
be  carried  forward  until  the  program  SETs  CARRY  OFF. 

-M-USE  Cust  ORDER  Cust_id-L~ 

SET  CARRY  TO  State-L- 

SET  FORMAT  TO  < . fmt  filename>~L~ 

READ-N- 

-NOTE-Issuing  a  SET  CARRY  TO  automatically  SETs  CARRY  ON.  Also, 
you  can  carry  forward  a  field  without  displaying  it.  To  do  this, 
SET  CARRY  TO  the  field  and  then  SET  CARRY  OFF.  -ENDBOX- 

Variation  #2  —  Entering  Default  Data 

With  the  DEFAULT  option  of  the  @ . . . SAY . . -GET  command,  you  can 
save  the  user  keystrokes  by  entering  default  data  into  the 
database  file.  A  typical  use  for  this  option  is  to  enter  today's 
date  in  a  date  field: 
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-M-@...SAY  "Enter  transaction  date:  ";~L~ 

GET  Date_trans  DEFAULT  DATE ( ) -N- 

Other  uses  for  this  option  might  be  to  enter  a  default  state 
(DEFAULT  "State  =  CA")  or  order  quantity  (DEFAULT  "Part  qty  = 

1")  . 

-H2 -DELETING  DATA  FROM  THE  DATABASE 

Deleting  records  works  the  same  in  dBASE  programming  as  it  does 
at  the  dot  prompt.  Position  the  record  pointer  to  the  correct 
record  number  and  then  DELETE  the  record. 

This  code  example  permits  users  to  delete  records  from  Employee 
one  at  a  time.  The  @ .. .SAY. .. GETS  capture  the  user's  entry  of  a 
last  name  and  first  name.  Then,  if  a  SEEK()  on  that  name  is 
successful,  the  record  is  DELETEd  and  erased  is  set  to  .T..  (If 
the  SEEK()  fails,  an  error  message  appears.)  This  cycle  repeats 
until  the  user  presses  RETURN  with  no  name  (enters  a  null)  at  the 
name  prompt.  Then  the  routine  PACKS  the  database  file  and 
terminates . 

-TIP-To  increase  program  efficiency,  you  might  want  to  put  the 
subroutine  containing  the  PACK  command  in  the  exit  code  at  the 
end  of  your  main  program.  This  means  that  dBASE  only  packs  once 
(when  the  user  exits  the  program)  rather  than  every  time  the  user 
marks  records  for  deletion.  Chapter  6  discusses  the  main 
program. -ENDBOX- 

-M-erased  =  . F.-L- 
USE  Employea-L- 
DO  WHILE  .T.-L- 

@  12,10  SAY  "Last  name:  "  GET  mlastname  PICTURE-L- 
" ! XXXXXXXXXXXXXX"-L- 

@  14,10  SAY  "First  name:  "  GET  mfirstname  PICTURE-L- 

":xxxxxxxxx"~l~ 

READ-L- 

IF  ""  <>  TRIM(mlastname+mf irstname) -L~ 

I?  SEEK(mlastname+mfirstname) -L- 
DELETE-L- 
CLEAR-L- 
erased  =  .T.-L- 
ELSE-L- 

@  20,20  SAY  "Name  not  found.  Please  re-enter . "-L- 
ENDIF-L- 
ELSE-L- 

IF  erased-L- 
PACK-L- 
ENDIF-L- 
EXIT-L- 
ENDIF-L- 
ENDDO-N- 

Variations  —  DELETE  ALL,  RECALL,  and  SET  DELETED  ON 
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You  can  DELETE  ALL  records  matching  a  specified  condition,  such 
as  all  customers  from  a  particular  state.  To  do  this,  modify  the 
previous  example  to  GET  the  user's  entry  of  a  state  and  then 
DELETE  ALL  FOR  State  -  instate. 

You  can  RECALL  a  DELETEd  record  as  long  as  you  haven't  PACKed  the 
database  file.  Don't  forget  to  issue  the  PACK  command  to  save 
disk  space,  once  you're  sure  you  want  to  permanently  erase 
DELETEd  records. 

If  you  want  commands  like  LIST  and  LOCATE  to  skip  DELETEd 
records,  SET  DELETED  ON.  RECALL  ALL  has  no  effect  with  SET 
DELETED  ON. 

-H2 -CREATING  MULTI-FILE  FORMS 

A  multi-tile  form  is  a  screen  form  that  draws  fields  from  more 
than  one  database  file.  You  cannot  create  multi-file  forms  with 
the  forms  generator,  but  you  can  do  so  in  a  program.  The  routine 
shown  below  first  USEs  Goods  and  Vendors  in  separate  work  areas. 
Then  it  SETs  RELATION  between  the  files  on  the  key  field, 

Vendor  id.  Next,  the  Multfile  format  file  displays  GETs  for  all 
desired  fields  in  the  multi-file  form  except  the  key  field. 

The  key  field  is  handled  separately,  because  its  contents  in  each 
database  file  must  remain  identical.  Changing  the  key  field  in 
one  file  without  changing  it  in  the  other  would  destroy  the 
RELATION  between  the  files.  To  prevent  this,  the  routine  places 
the  contents  of  the  key  into  a  memory  variable,  mkey,  and 
Multfile. fmt  GETs  that  variable. 

Finally,  special  EDIT  end  REPLACE  commands  ensure  identical 
editing  of  both  keys.  The  NEXT  1  clause  restricts  the  scope  of 
the  EDIT  to  the  current  record,  so  that  the  record  pointers  don't 
move.  The  multiple  REPLACE  updates  the  key  field  in  both  files 
simultaneously - 

-M-USE  Goods  ORDER  Vendor  id-L- 

USE  Vendors  ORDER  Vendor  Id  IN  2-L- 

SET  RELATION  TO  Vendor_i3  INTO  Vendors-L- 

SET  FORMAT  TO  Multfile-L- 

mkey  =  Vendor_id-L~ 

EDIT  NEXT  1-L- 

REPLACE  Goods->Vendor  id  WITH  mkey,  ;-L- 
Vendors->Vendor_id  WITH  mkey-L- 

*  ...  Multfile. fmt-L- 

@  3,30  SAY  "INVENTORY  DATABASE "-L- 

@  5,11  SAY  "Vendor  no:  "  GET  mkey  PICTURE  "!999"~L~ 

*  ...  Remaining  @...SAYs  from  Goods  database  file-L- 
@  13,31  SAY  "VENDORS  DATABASE"-L- 

@  16,11  SAY  "Vendor:  "  GET  Vendors->Vendor  FUNCTION  "!"~L~ 

*  ...  Remaining  §...SAYs  from  Vendors  database  file-N- 
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-WARNING-Do  not  update  the  key  fields  in  the  two  files  with 
separate  REPLACE  commands.  The  key  field  would  change  after  the 
first  REPLACE,  destroying  the  RELATION  between  the  files,  '’’he 
second  REPLACE  would  then  either  update  the  wrong  record,  or 
corrupt  both  the  database  file  and  the  index  by  REPLACEing  to  the 
phantom  record  at  the  end  of  the  second  file.-ENDBOX- 

See  Chapter  13  for  more  information  on  relating  database  files  in 
a  program. 

-H2 -  WORKING  WITH  LARGE  FILES 

When  your  program  writes  a  file  to  disk,  DOS  places  the  data  ir. 
sectors.  As  the  sectors  fill,  the  overflow  is  written  to  the  next 
available  sector,  which  may  not  be  contiguous.  This  means  that, 
after  a  while,  the  file  can  become  very  fragmented  on  the  disk. 
The  heads  on  your  hard  disk  have  to  jump  from  sector  to  sector, 
and  access  times  get  longer. 

You  can  maximize  performance  with  large  database  files  by 
preventing  this  fragmentation.  Create  the  file  and  then  APPEND  as 
many  BLANK  records  as  you  estimate  the  file  will  need  at  its 
largest.  Next,  create  your  indexes.  (Indexes  are  disk-based  too, 
so  they're  also  subject  to  fragmentation.) 

Now  you  have  a  very  large  database  file  containing  blank  data. 
Instead  of  APPENDing  records,  EDIT  the  first  blank  record  in  the 
file.  To  delete  a  record,  GO  to  the  record  and  blank  out  the 
fields  (REPLACE  WITH  SPACE(<n>)).  When  running  reports  or 
queries,  exclude  blank  records  with  SET  FILTER  TO  LEN(<key 
field>) ■ <>  0. 

These  changes  will  not  be  detectable  to  users,  and  will  eliminate 
complaints  that  access  time  slows  down  as  the  file  size 
increases.  This  method  is  also  beneficial  in  a  multi-user 
environment:  you  don't  have  to  lock  the  entire  file  to  add  a 
record,  since  EDIT  requires  only  an  RL0CK() . 
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[VENDOR 

DYNAMITE  INDUSTRIES 
ACME  ENTERPRISES 
DEPENDO  INDUSTRIES 
EXECUTIVE  ENTERPRISES 
SOUTHERN  SALES  LTD. 

KIRK  ENTERPRISES 
PASTUARE  FURNITURE  MFC. 
HARVARD  FURNITURE  MFC. 


•PHONE  VEND  CONTACT  V 
( 616)232-3000 
(319)199-1080 
(616)233-5400 
(415)305-2800 
(808)202-5100 
(415)305-7000 
( 808 ) 213—4400 
(808)233-5620 


J.P.  MORGAN.  SR. 
KIRK  PETERS 
T.D.  KIMBLE 
JIM  SMITHSON 
TIM  DAUIDSON 
JIM  KIRK 
DAUID  SOUP 
DAUID  SAMSON 
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-HI -WORKING  WITH  DATA  TYPES 

dBASE  IV  provides  six  data  types:  character,  fixed,  floating, 
date,  memo,  and  logical.  This  chapter  contains  summaries  of  how 
to  format  and  manipulate  the  different  types  of  data,  as  well  as 
examples  of  how  to  use  them  in  program  code.  Chapter  1  of 
Language  Reference  provides  more  information  on  all  the  data 
types. 


-H2-WHAT  THIS  CHAPTER  COVERS 
This  chapter  covers  the  following  topics: 
-o-Handling  character  and  numeric  data 
-o-Handling  date  and  time  data 
-o-Handling  memo  field  data 
-o-Handling  logical  data 
-o-Converting  data  types-ENDLIST- 
-H2 -HANDLING  CHARACTER  DATA 


Much  of  the  data  processed  by  your  programs  will  be  character 
data.  Remember  that  character  data  can  consist  of  numbers  as  well 
as  character  strings,  as  long  as  you  don't  have  to  use  the 
numbers  in  mathematical  computations. 

Use  the  following  commands  and  functions  to  format  character 
data.  Look  up  unfamiliar  ones  in  Language  Reference . 


-o-UPPERO  —  changes  to  upper  case 

-o-LOWER ( )  —  changes  to  lower  case 

-o-LTRIMO  —  trims  leading  blanks 

~o~RrRIM()  —  trims  trailing  blanks 

-o -?/??  . . .  FUNCTION  "T"  —  trims  all  blanks 

~o~?/??  ...  FUNCTION  "I"  —  centers  a  string 

-o-?/??  . . .  FUNCTION  "J"  —  right-justifies  a  string 

-o-?/??  ...  FUNCTION  "B"  —  left-justifies  a  string 

Table  10-1  shows  some  common  ways  to  manipulate  character  data  in 
a  program. 


-TABLE-Table  10-l\mManipulating  character  data 
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Task 

Measure  length  of  string 
Find  position  in  substring 
Extract  a  substring 
Extract  from  left 
Extract  from  right 
Insert  one  string  into 
another* 1 
Repeat  a  string 
Concatenate  strings 
Compare  strings  by  ASCII 
value 

Compare  strings  using 
wildcards 


Example 

LEN ( Part_name ) 

?  AT ( " , " , "Monday , Tuesday 
?  SUBSTR ( Part_id ,7,4) 

?  LEFT(Part_name,9) 

?  RIGHT (mpart_id, 4 ) 

?  STUFF(mterms,8,2,mdays) 

?  REPLICATE 16) 

?  mfirstname  +  mlastname 
?  mpart_idl  =  mpart_id2 

LIST  Part_id  FOR  ; 

LIKE ( "*-2??-*" , Part_id) 


NOTE: 

1.  Assume  mterms  =  "TERMS:  days"  and  mdays  =  "30" ENDTABLE - 


These  data  manipulation  capabilities  are  very  useful  in  a 
programming  environment.  The  following  code  examples  show  how. 

The  first  brief  routine  does  an  error  procedure  if  a  null  string 
is  encountered: 

-M-IF  ""  =  TRIM (mentry ) - L~ 
do  Error- L~ 

ENDIF-N- 

Note  that  dBASE  IV  compares  each  character  until  it  runs  out  of 
characters  on  the  right  side  of  the  relational  operator.  For 
instance,  this  comparison: 


.  ?  "abed"  =  "abc" 


gives  a  .T.  response.  But  this  comparison: 

.  ?  "abc"  =  "abed" 

gives  a  .F.  response.  If  you  SET  EXACT  ON,  however,  dBASE  IV 
compares  the  strings  exactly. 

The  example  below  uses  both  the  -  (minus)  and  +  (plus) 
concatenation  operators  to  print  a  city  and  state  in  the  form 
Contoocook,  NH  03229.  Note  that  the  -  operator  moves  any  blank 
spaces  filling  out  the  City  field  to  the  right  of  mstate.  This 
aligns  the  zip  codes  vertically. 


-M-mstate  =  ",  "  +  State  +  "  "-L- 
?  City  -  mstate  +  Zip-N- 
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You  can  extract  a  substring  without  knowing  its  position  in  the 
primary  string.  In  the  following  routine,  the  AT ( )  function 
identifies  the  starting  position  of  mpart  in  the  Part  name  field. 
LEN()  determines  the  length  of  the  substring. 

-M-mpart  =  "sofa"-L- 

?  SUBSTR ( Partname ,  AT(mpart, Part_name) , LEN (mpart) ) ~N~ 

The  following  example  uses  AT ( )  and  SUBSTR()  to  evaluate  a  list. 
The  variable  mfilelist  contains  a  list  of  filenames  separated  by 
commas.  (Of  course,  you  could  evaluate  any  type  of  list.)  The 
first  line  within  the  DO  WHILE  loop  prints  the  first  word  in  the 
list,  up  to  but  not  including  the  first  comma.  The  second  line 
stores  the  rest  of  the  string  back  to  mfilelist.  Note  that  the 
AT ( )  function  determines  the  substring  length  in  the  first  line 
and  the  substring  starting  position  in  the  second.  The  DO  WHILE 
condition  causes  this  process  to  continue  as  long  as  there  are 
commas  in  mfilelist,  that  is,  until  only  one  word  remains.  Then 
the  loop  ends  and  the  program  prints  the  last  filename  in  the 
list. 

-M-mfilelist  =  "Acct  rec, Client, Employee, Orders, Vendors"-L- 
DO  WHILE  AT ( " , " ,  mfilelist)  >  0-L- 

?  SUBSTR (mfilelist,  1,  AT ( " , ", mfilelist) -1) ~L- 
mfilelist  =  SUBSTR(mfilelist,  AT( mfilelist) +1) -L- 
ENDDO-L- 
?  mfilelist-N- 

-H2 -HAND LING  NUMERIC  DATA 

This  section  explains  how  to  format  numbers  and  perform  numeric 
calculations  in  a  program.  The  comment  box  explains  the  two  types 
of  numbers  provided  with  dBASE  IV. 

-CCMMENX-dBASE  IV  supports  both  -I-Binary  Coded  Decimal-R-  (type 
N)  and  -I-floating  point-I-  (type  F)  numbers.  This  represents  a 
change  from  earlier  versions  of  dBASE,  which  supported  floating 
point  numbers  only. 

BCD  numbers  contain  a  decimal  representation  of  the  number.  You 
normally  use  BCD  numbers  for  accounting  applications,  with  the 
decimals  set  to  two  places.  The  use  of  BCD  numbers  eliminates 
problems  with  numeric  comparison  and  rounding  errors  that  occur 
with  floating  point  numbers.  This  ensures  that  balances  total 
properly. 

In  floating  point  numbers,  the  decimal  point  moves,  or  floats, 
depending  on  the  size  of  the  number.  Typically,  you  use  floating 
point  numbers  for  scientific  and  engineering  calculations  that 
require  very  large  or  small  numbers ,  or  that  multiply  and  divide 
repeatedly.  Floating  point  numbers  are  often  expressed  in 
scientific  (exponential)  notation  (see  "Formatting  numbers") . 


May  17,  1988 


Page  3 


Programming  with  dBASE  IV 


Ch.  10,  Data  Types 


Use  CREATE/MODI F Y  STRUCTURE  to  define  fixed  and  floating  point 
numeric  fields.  The  data  type  of  a  numeric  memory  variable 
depends  upon  how  you  create  it.  If  you  create  it  from  a  field, 
the  type  will  match  the  field  type.  If  you  create  it  from  a 
numeric  constant,  the  variable  will  be  type  N.  If  you  create  it 
by  a  command  or  function,  the  type  will  depend  on  the  command  or 
function. 

Use  FLOAT (<BCD  number>)  to  convert  a  BCD  number  to  floating 
point,  and  FIXED(<floating  point  number>)  to  convert  a  floating 
point  number  to  BCD.  When  you  combine  both  BCD  and  floating  point 
numbers  in  an  expression,  dBASE  IV  automatically  converts  all  the 
BCD  numbers  to  floating  point. -ENDCOM- 

-H3- Formatting  and  Manipulating  Numbers 

Here  is  a  brief  summary  of  the  commands,  functions,  and  PICTURE 
templates  and  FUNCTIONS  that  format  numeric  data.  See  Language 
Reference  for  more  information  on  the  individual  commands, 
functions,  or  options. 

-o-To  round  off  numbers  —  ROUND() 

-o-To  show  number  in  exponential  notation  —  *  FUNCTION 

-o-To  limit  display  to  digits,  signs,  and  blanks  —  9  or  # 

PICTURE 

-o-To  show  zero  values  as  blank  string  —  Z  FUNCTION 

-o-To  show  leading  zeros  as  zeros,  dollar  signs,  or  asterisks  — 
L,  $,  or  *  PICTURE 

-o-To  show  number  in  standard  currency  format  —  $  FUNCTION 

-o-To  specify  and  position  currency  symbol  —  SET  CURRENCY  TO  and 
SET  CURRENCY  LEFT/right 

-o-To  show  CR  after  positive  number,  DB  after  negative  —  C  and  X 
FUNCTIONS,  respectively 

-o-To  show  negative  numbers  in  parentheses  —  (  FUNCTION 

-o-To  specify  desired  decimal  symbol  and  number  of  decimals  — 
SET  POINT  TO  and  SET  DECIMALS  TO 

-o-To  specify  separator  character  —  SET  SEPARATOR  TO 

-o-To  center,  right-justify  and  left-justify  data  —  I,  J,  and  B 
FUNCTIONS,  respect ively-ENDLIST- 

Table  10-2  shows  how  to  manipulate  numbers  for  use  in  programs. 
Look  up  any  unfamiliar  commands  or  functions  in  Language 
Reference  for  more  detail. 
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-TABLE-Table  10-2\mManipulating  numeric  data* 1 2'^ 


Task 


Example 


Compute  arithmetic 
expression 
Count  items 


Sum  values 


Average  values 
Compute  distribution 


Compute  minimum 
value3 

Compute  maximum 
value3 


?  (3*PI() )/4 

CALCULATE  CNT ( )  TO  mcount 
or 

COUNT  TO  mcount 

CALCULATE  SUM(mcost*mquantity)  TO  mtotal 
or 

SUM  mcost*mquantity  TO  mtotal 
or 

TOTAL  ON  Part  id  TO  Part  tot 

CALCULATE  AVG  fCcst )  TO  mavg_cost 
or 

AVERAGE  Cost  TO  mavg_cost 

CALCULATE  STD(mcost)  TO  mstd_cost 
or 

CALCULATE  VAR(mcost)  TO  mvar  cost 

CALCULATE  MIN (Cost)  TO  mmin_cost 
or 

?  MIN(mdatel,mdate2) 

CALCULATE  MAX ( Date_trans )  TO  mmax_date 
or 

?  MAX(mhired,mfired) 


NOTES : 

1.  This  table  shows  only  the  statistical  functions.  dBASE  IV  also 
provides  arithmetic,  trigonometric,  and  financial  functions.  See 
Chapter  1  of  Language  Reference  for  more  detail,  and  for  an 
explanation  of  operator  precedence. 

2.  SET  TALK  ON  in  order  to  see  the  results  of  SUM,  AVERAGE,  and 
COUNT. 

3.  MIN ( )  and  MAX()  with  CALCULATE  return  the  smallest  or  largest 
record  in  the  named  field.  As  stand-alone  functions,  they  return 
the  smaller  or  larger  of  two  specified  va) ues. -ENDTABLE- 


CALCULATE  can  carry  out  a  number  of  operations  in  one  pass 
through  the  database  file,  for  example: 

-M-CALCULATE  AVG(Cost) ,  STD(Cost)  TO  mavg_cost,  mstd_cost-N- 

The  following  example  counts  how  many  orders  have  been  placed  by 
a  particular  customer.  After  ORDERing  the  Orders  database  file  by 
the  Cust_id  TAG,  the  routine  GETS  a  customer  number  from  the 
user.  It  SEEKS  the  number  in  the  file,  and  COUNTS  how  many  orders 
(records)  the  customer  has  made.  It  also  CALCULATES  the  average 
quantity  of  parts  ordered  by  the  customer. 

-M-USE  Orders  TAG  Cust_id-L- 

@ . . . SAY  "Enter  customer  ID:  "  GET  Cust_id~L~ 

STORE  0  TO  morder_cnt,mavg_quant-L~ 
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mcust  =  Cust_id-L~ 

SEEK  mcust-L- 

CALCULATE  CNT ( ) ,  AVG (Part_gty)  TO  morder_cnt,  mavg  quant  ;-L- 
WHILE  mcust  =  Cust_id-N- 

-H2- HANDLING  DATE  DATA 


Although  it  lets  you  display  dates  in  a  variety  of  formats,  dBASE 
IV  processes  date  fields  and  date  type  memory  variables  as 
special  numbers  in  the  form  CCYY/MM/DD  (year/month/ day ) .  The 
following  commands  and  functions  format  date  type  data: 


-o-To  specify  international  date  format  —  SET  DATE 
-o-To  display  4-digit  year  —  SET  CENTURY 
-o-Tc  define  separator  character  —  SET  MARK  TO 
-o-Tc  return  DD  Mon  YY  or  Mon  DD,  YY  —  DMY()  or  MDY ( ) 

-o-To  return  day  of  week  by  number  or  name  —  DOW()  or  CDOW() 
-o-To  return  day  of  month  by  number  —  DAY() 

-o-To  return  month  by  number  or  name  —  MONTH ()  or  CMONTH ( ) 
-o-To  return  year  —  YEAR() -ENDLIST- 

dBASE  IV  considers  Sunday  the  first  day  of  the  week. 

Table  10-3  shows  how  to  manipulate  date  data  in  programs. 
-TABLE-Table  10-3\mManipulating  date  data 


Task 

Return  system  date 
Find  earliest  of  two  dates 
Find  latest  of  two  dates 
Compare  dates 
Check  for  blank  date* 1 
Add  number  to  date 
Subtract  number  from  date 
Subtract  two  dates 


Example 
?  DATE() 

?  MIN(mdatel ,mdate2) 
?  MAX(mdatel,mdate2) 
?  datel  <  date2 
?  mblank  =  mdate 
?  DATE()  +  45 
?  DATE()  -  30 
?  mdatel  -  mdate2 


Note: 

1.  Assumes  mblank  =  {  /  /  ).-ENDTABLE- 


You  can  use  the  LIKE()  function  to  COUNT  the  number  of  records  in 
a  given  month.  For  example,  the  following  routine  COUNTS  the 
number  of  March  records  in  the  Orders  database  file: 


-M-USE  Orders  ORDER  Trans  date-L- 

COUNT  FOR  LIKE("03/??/87" , DTOC (Trans_date) )  TO  March_cnt-N- 
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The  next  example  initializes  mdiff  with  the  difference  between 
today's  date  and  the  transaction  date.  The  routine  issues  a  dun 
letter  if  the  account  is  between  30  and  45  days  past  due,  and  a 
stronger  letter  if  the  account  is  more  than  45  days  past  due. 

-M-mdiff  =  DATE ( )  -  Date_trans~L~ 

DO  CASE-L- 

CASE  mdiff  >  30  .AND.  mdiff  <  45-L- 
DO  Dunlettr-L- 
CASE  mdiff  >=  45-L- 
DO  Nasty- L- 
ENDCASE-N- 

If  your  program  computes  dates  arithmetically,  later  comparisons 
could  be  faulty.  For  example: 

.  indate  =  (07/01/1988) 

07/01/1988 

.  outdate  =  indate  +  .25 

07/01/1988 

.  ?  indate 

07/01/1988 

.  ?  outdate 

07/01/1988 

.  ?  indate  =  outdate 


.F. 

While  indate  and  outdate  are  on  the  same  day,  dBASE  internally 
stores  a  value  for  outdate  that  is  .25  greater  than  the  value  of 
indate. 

If  you  don't  want  differences  of  less  than  a  day  to  show  up  in  a 
comparison,  convert  the  date  type  data  to  character  type  before 
comparing: 

.  ?  DTOC(mindate)  =  ?  DTOC(moutdate) 

.T. 

-H2 -HANDLING  TIME  DATA 

While  there  is  no  time  data  type,  you  can  use  the  TIME ( ) 
function,  SET  HOURS,  SET  CLOCK  to  format  time  data: 


Hay  17,  1988 


Page  7 


Programming  with  dBASE  IV 


Ch.  10,  Data  Types  ■ 


-o-To  return  system  time  —  T1ME() 

-o-To  specify  12-  or  24-hour  format  —  SET  HOURS  TO  [12/24] 
-o-Display  and  position  clock  —  SET  CLOCK  ON  and  SET  CLOCK  TO 

-NOTE-Full-screen  commands  like  BROWSE  and  EDIT  always  display 
the  clock  in  the  upper  right-hand  corner  of  the  screen.  SET  CLOCK 
does  not  affect  these  commands.  SET  CLOCK  OFF  speeds  up  program 
performance . -ENDBOX¬ 
TIME  ()  always  returns  a  character  string.  You  can  store  the 
current  time  in  a  memory  variable: 

-M-mnow  =  TIME ( ) -N~ 

You  can  then  split  mnow  into  substrings  if  you  wanted  to  use  only 
part  of  the  time.  For  example,  if  it's  now  2:30  and  43  seconds 
(14:30:43),  the  instruction 

-M-mnow  =  LEFT (mnow, 5) -N- 

puts  the  string  14:30  into  mnow. 

Validating  time  data  entered  by  the  user  requires  a  short  routine 
like  the  following.  If  you're  using  a  24-hour  clock,  change  12 
to  24. 

-M-mtime  =  SPACE (5) -L- 

@  ...  GET  mtimc  PICTURE  "99:99"  VALID;-L~ 

VAL(LEFT (mtime, 2 ) )  >=  0  .AND.  VAL(LEFT (mtime , 2 ) )  <=  12  ;-L- 
•AND.  VAL(RIGHT(mtime, 2) )  >=  0  .AND.  VAL(RIGHT (mtime , 2 ) )  <  60 
;-L- 

ERROR  "Enter  minutes  from  C  to  59,  hours  from  0  to  12"-L~ 
READ-N- 

The  following  routine  GETs  a  beginning  and  ending  time  from  the 
user.  Then,  after  transforming  the  entries  into  seconds 
(mbegsecs  and  mend_secs) ,  it  calculates  mdiff,  the  difference 
between  the  two  times. 

Next,  it  converts  the  difference  back  to  hours,  minutes,  and 
seconds.  For  hours,  it  divides  mdiff  by  3600.  The  INTO  function 
then  reduces  the  quotient  to  whole  hours.  The  IIF()  subtracts  the 
equivalent  number  of  seconds  (if  any)  from  mdiff.  This  process  is 
repeated  for  minutes,  and  then  the  routine  computes  the  remaining) 
seconds  with  the  MOD()  function.  Finally,  the  routine  displays 
the  time  difference,  placing  a  0  before  single-digit  hours, 
minutes,  or  seconds. 


"  GET  mbeg_time  PICT  "##:##:##" 
GET  mend  time  PICT  "##:##:##"- L- 


~M~ 

@  7,10  SAY  "Enter  starting  time: 
-L~ 

@  9,10  SAY  "Enter  ending  time:  " 
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READ-L- 

mbegsecs  =  (VAL(LEFT(mbeg_time, 2) ) *3600)  +  ;~L~ 

(VAL (SUBSTR (mbeg  time , 4 , 2) ) *60)  +  ( VAL(RIGHT (mbegtime , 2 ) ) ) -L- 
mend  secs  =  (VAL( LEFT (mend  time , 2 )) *3600)  +  ;-L~ 

( VALTSUBSTR (mendtime ,4,2)7*60)+ (VAL (RIGHT (mend_ti me , 2 ) ) ) -L- 
mdiff  =  mbegsecs  -  mend  secs-L- 
\m~  •> 

STORE  0  TO  mhours,  mminutes,  mseconds-L- 
IF  mdiff  >  0-L- 

mhours  =  INT (mdif f/3600) -L~ 

mdiff  =  mdiff  -  IIF(mhours  >  0 , INT (mhours*3600) , 0) -L- 
mminutes  =  INT (mdif f/60) -L- 

mdiff  =  mdiff  -  IIFfmminutes  >  0 , INT (mminutes*60) , 0) ~L~ 
mseconds  =  MOD (mdif f, 60) -L- 
ENDIF-L- 

mhours  =  IIF(mhours>9 ,STR(mhours, 2) , "0"+STR(mhours, 1) ) -L- 
mminutes  =  IIF (mminutes>9 , STR (mminutes,  2 )  ,  M0"+STR (mminutes ,1)  )  -L~ 
mseconds  =  IIF(mseconds>9,STR(mseconds, 2) , "0"+STR(mseconds, 1) ) -L- 
@  12,10  SAY  "The  time  difference  is  ''  ;~L~ 

+  mhours  +  " +  mminutes  +  " : "  +  mseconds-N- 

-H2- HANDLING  MEMO  FIELD  DATA 

Memo  fields  are  actually  character  data,  but  dBASE  IV  maintains 
them  in  separate  variable-length  text  files. 

The  maximum  memo  field  size  is  64K.  To  make  the  most  efficient 
use  of  disk  space,  be  sure  to  change  block  size  with  SET 
BLOCKSIZE  or  in  Config.db  if  your  application  requires  large  memo 
fields.  The  default  block  size  is  512K,  which  you  get  when  you 
SET  BLOCKSIZE  TO  1. 


You  can  format  memo  fields  using  the  following  commands  and 
system  memory  variables.  (See  Chapter  5  of  Language  Reference  for 
information  on  the  system  variables.) 

-o-To  change  display  width  —  SET  MEMOWIDTH 

-o-To  display  in  a  window  —  @. . .SAY. . .GET  WINDOW  option 

-o-To  change  left  margin  —  _lmargin 

-o-To  change  right  margin  —  _rmargin-ENDLIST~ 

Table  10-4  shows  how  to  work  with  memo  fields  in  programs. 

-TABLE- Table  10-4\mManipulating  memo  field  data 

Task  Example 


Find  length  of  field 
Find  where  string  starts 
in  memo  field 
Extract  string 


?  LEN( Comment) 

?  AT ("Cost  =  $615. 00", Comment) 
?  SUBSTR (Comment ,12,5) 
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Append  text  from  file1 
Overwrite  text  from  file 

Replace  text  in  field2 
Add  text  to  field2 
Copy  text  elsewhere 
Copy  without  overwrite 
Display/print  field 


Return  number  of  lines 
Return  specific  line 


APPEND  MEMO  Comment  FROM  Sample 
APPEND  MEMO  Comment  FROM  Sample  ; 
OVERWRITE 

REPLACE  Note  WITH  Notel 
REPLACE  Note  WITH  Notel  ADDITIVE 
COPY  MEMO  Comment  TO  Sample 
COPY  MEMO  Comment  TO  Sample  ADDITIVE 
LIST  Comment 
or 

?  Comment 

?  MEMLINES  (Comment) 

?  MLINE( Comment, 2) 


Notes: 

1.  You  can  use  APPEND  MEMO  to  read  the  contents  of  any  file,  even 
a  program  object  (.dbo)  file,  into  a  memo  field. 

2.  REPLACE  converts  character  data  to  memo  fields  and  vice  versa. 
In  converting  memo  fields  to  character  fields,  REPLACE  truncates 
the  data  to  fit  the  assigned  field  width. -ENDTABLE- 


The  example  and  variation  below  are  based  on  th  following 
hypothetical  code: 


-M-SET  MEMOWIDTH  TO  20-L- 

?  Merchant-L- 

?-L- 

?  MEMLINES (Merchant) ~L~ 
?-L- 

?  MLINE (Merchant, 3) ~L~ 
\m-N- 

The  quality  of  mercy 
is  not  strained.  It 
falleth  as  a  gentle 
rain  from  Heaven . . . 

\m 

4 

\m 

falleth  as  a  gentle 


-TYPES ETTER-Following  side  by  side  with  previous  version. -BYE- 


-M-SET  MEMOWIDTH  TO  30-L- 
?  Merchant- L~ 

?-L- 

?  MEMLINES (Merchant) -L~ 

?-L- 

?  MLINE (Merchant, 3) ~L~ 

\m-N~ 

The  guality  of  mercy  is  not 
strained.  It  falleth  as  a 
gentle  rain  from  Heaven... 
\m 

3 

\m 
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gentle  rain  f roe  Heaven... 

You  can  print  the  line  containing  the  phrase  gentle  rain  even  if 
you  don't  know  which  line  it  is.  The  next  routine,  which  works 
with  any  multiple-word  phrase,  first  assigns  the  width  of  the 
memo  field  to  mwidth.  Then  it  uses  AT()  to  find  mposition,  the 
starting  position  of  the  phrase  gentle  rain. 

Next,  the  routine  computes  mline,  the  line  that  mposition  is  on. 
To  do  this,  it  divides  mposition  by  mwidth  and  calculates  the 
CEILING ( ) ,  the  next  largest  integer.  In  the  example  below, 

CEILING (55/35)  =  3.  Finally,  the  routine  prints  mline. 

-M-mwidth  =  35-L- 

SET  MEMOWIDTH  TO  mwidth-L- 

msearch  =  "gentle  rain" 

mposition  =  AT (msearch, Merchant) ~L~ 

m_line  =  CEILING (mposition/mwj dth) -L~ 

?  MLINE (Merchant, m_line) ~N~ 

Vari ation  —  When  the  phrase  wraps  on  two  lines 

If  a  phrase  wraps  at  the  right  margin,  the  previous  routine  only 
prints  the  words  on  the  first  line.  To  print  the  entire  wrapped 
phrase,  add  the  following  DO  WHILE  loop  to  the  routine.  For  each 
pair  of  words,  this  code  defines  msearch  as  the  substring  from 
the  beginning  of  the  second  word  to  the  end  of  the  phrase.  Then 
it  sets  mposition  as  the  beginning  of  msearch.  If  m_line 
(calculated  as  before)  has  a  different  value,  the  routine  prints 
this  new  line  as  well.  The  loop  continues  as  long  as  additional 
words,  with  spaces  between  them,  remain  in  the  phrase. 

-M-DO  WHILE  "  "  $  msearch-L- 
moldline  =  m_line~L~ 

msearch  =  RIGHT (msearch, LEN (msearch)  -  AT ( "  ", msearch) ) -L- 
mposition  =  AT (msearch, Merchant) -L~ 
m_line  =  CEILING (mposition/mwidth) -L- 
IF  m_line  <>  moldline-L- 

?  MLINE (Merchant, m_line) -L- 
ENDIF-L- 
ENDDO-N- 

-H2 -HANDLING  LOGICAL  DATA 

Logical  data  can  have  only  two  values,  .T.  (true)  or  .F.  (false). 
Thus,  logical  variables  are  handy  for  controlling  program  flow  or 
checking  the  status  of  conditions. 

Here  are  some  of  the  uses  for  logical  data: 

-o-In  a  positive  condition,  such  as  LIST  FOR  m_is_late 

-o-In  a  negative  condition,  such  as  LIST  FOR  .NOT.  m_is_late 
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-o-To  form  complex  expressions,  such  as  IF  -NOT.  (EOF()  .AND. 
mfound) 


Use  string  equivalents  instead  of  .T.  and  .F.,  which  might 
confuse  users.  For  example,  you  can  make  .T.  appear  as  Y  and  .F. 
as  N: 

-M-@  ...  SAY  "Print  now?  (Y/N)"  GET  mnow  PICTURE  "Y"  ;-L- 
VALID  mnow  $  "YN"  ERROR  "Enter  Y  or  N  only."-N- 

The  .OR.  logical  operator  is  actually  an  inclusive  or.  In  other 
words,  X  .OR.  Y  means  X  or  Y,  or  both  X  and  Y.  dBASE  IV  doesn't 
provide  an  exclusive  or  (also  known  as  XOR) ,  but  you  can  easily 
construct  one  using  logical  operators: 

-M-(X  .OR.  Y)  .AND.  .NOT.  (X  .AND.  Y) -N- 

This  routine  uses  the  logical  operators  .NOT.  and  .AND.,  plus  the 
FOUND ()  and  EOF ( )  functions,  to  process  the  possible  outcomes  of 
a  search  with  SET  NEAR  ON.  If  mkey  (the  vendor  code)  is  found, 
FOUND ()  is  set  to  .T.  and  the  first  CASE  prints  the  vendor  data. 
If  mkey  is  not  found,  the  record  pointer  stops  at  the  next  record 
in  alphabetical  key  order.  Thus,  in  the  second  CASE,  both  F0UND() 
and  EOF ( )  are  .NOT.  true.  OTHERWISE,  a  message  indicates  that  the 
record  pointer  is  at  the  end  of  the  file. 

-M-USE  Vendors  ORDER  Vend_id~L~ 

SET  NEAR  ON-L- 
SEEK  mkey-L- 
DO  CASE-L- 

CASE  FOUND ( )~L~ 

?  Vendor  id.  Vendor,  Phone  vend,  City_V-L- 
CASE  .NOT.  TFOUNDO  .AND.  EOFT) ) ~L~ 

?  "Vendor  not  found. "-L- 

?  "Next  vendor  (alphabetically)  will  display. "-L- 
OTHERWISE  &&  EOF ( )  =  .T.-L- 
?  "Vendor  not  found. "-L- 
?  "Record  pointer  at  bottom  of  file."-L~ 

ENDCASE-N- 

-H2 -CONVERTING  DATA  TYPES 

Sometimes  you  need  to  convert  data  from  one  type  to  another.  For 
example,  if  you  want  to  DISPLAY,  LIST,  or  ?/??  text  that  includes 
both  character  strings  and  a  date  or  number,  you  convert  the 
non-character  data  to  character  type.  Similarly,  calculations 
with  mixed  types  require  that  all  data  be  converted  to  one  type. 
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When  you  convert  the  data  types  of  fields  or  memory  variables, 
you  are  not  changing  field  types  in  the  database  file,  nor  are 
you  modifying  the  structure  of  the  database  file. 

Table  10-5  summarizes  how  to  convert  data  types.  See  Language 
Reference  for  more  information  on  the  individual  commands  and 
functions  listed  here. 

-TABLE-Table  10-5\mConverting  data  types 
Converts  Example 


Character  to  numeric 
Numeric  to  character 
Numeric  to  integer 
Character  to  date 
Date  to  character 
Date  to  string 
(for  indexing) 
Logical  to  character 
Character  to  memo 
Memo  to  character 


mpageno  =  VAL(mpage  no) 

?  "Amount  is  $”  +  STS(mamount , 5 , 2) 

?  INT(mamount) 

Orderdate  =  ("09/12/88") 

?  "The  date  is  "  +  DTOC ( DATE l ) ) 

INDEX  ON  DTOS ( Date_trans )  +  Cust_id  ; 
TO  TAG  Orders 

mfinished  =  IIF (mf inished, "Yes" , "No" ) 
REPLACE  mstring  WITH  mmemo 
REPLACE  mmemo  WITH  mstring 
or 

?  SUBSTR(mmemo, 240, 20) 
or 

?  MLINE (mmemo, 5) -ENDTABLE- 


The  following  code  excerpts  represent  some  typical  data  type 
conversions. 


To  convert  a  date  to  a  character  string  of  the  format  "MM/YY", 
extract  the  LEFT ( )  and  RIGHTO  two  characters  and  separate  them 
by  a  /  character.  This  example  assumes  the  MM/DD/YY  format. 

-M-mdate  =  LEFT ( { DATE ( ) ) , 3 )  +  RIGHT ( ( DATE ( ) } , 2 ) -N- 

To  index  by  date  and  amount  ordered,  convert  both  the  date  and 
numeric  fields  to  character  strings: 

-M-INDEX  ON  DTOS (Date_order)  +  STR(Amount, 8 , 2)  TO  Date_amt-N- 

This  next  example  increments  an  employee  identification  code  of 
the  form  C4263  by  one.  To  do  this,  it  converts  the  four  digits  to 
numeric  data  using  the  VAL()  function,  and  increments  the 
resulting  number  by  one.  Then  it  uses  STR()  to  convert  the  number 
back  to  a  character  string,  which  it  concatenates  with  the  single 
letter  on  the  LEFT ( )  end  of  the  identification  code.  It  does  all 
this  in  a  single  line  of  code. 

~M~m_id  =  LEFT(m_id,l)  +  STR ( VAL ( RIGHT (m_id, 4) )  +  1,4,0)~N~ 

This  last  routine  returns  the  percent  difference,  m  perc,  between 
two  numbers  as  a  character  string.  Usin^  the  IIF()  Tunction,  the 
routine  returns  a  0  percent  difference  if  the  difference  between 
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the  two  numbers  is  0  or  if  m_old  has  a  0  value  (to  avoid  dividing- 
by  0) .  Otherwise,  it  computes  the  percent  difference  in  the 
standard  manner.  Then  it  displays  the  percent  difference,  or  N/A 
if  m_old  is  0. 

-M-mdiff  =  mnew  -  m_old-L- 

m  perc  =  IIF(mdiff  =  0  .OR.  m  old  =  0,0,  ( (mdif f/m_old) *100) ) -L- 

nTperc  =  IIF(m_old  =  0 , "N/A" , STR (m_perc, 5 , 0) ) +"%"-L- 
?  m_perc-N~ 
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-Hl-ORDERING  THE  DATABASE  FILE 

Users  enter  data  into  a  database  file  in  raw  or  natural  order, 
that  is,  in  the  order  dictated  by  day-to-day  events.  However, 
they  usually  want  to  work  with  the  data  in  alphabetical,  numeric, 
or  date  order.  dBASE  IV  indexing  commands  and  functions  control 
the  order  in  which  data  appears. 

-H2-WHAT  THIS  CHAPTER  COVERS 


This  chapter  tells  you  how  to  control  the  order  of  data  in  a 
programming  environment.  The  topics  it  covers  are: 

-o-Creating  index  files 

-o-Modifying  index  files 

-o-Using  index  files 

-o-Determining  the  current  index  status 
-o-Estimating  the  index  file  size-ENDLIST- 
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-NOTE-Use  SORT  rather  than  INDEX  when  you  update  a  database  file 
rarely  but  often  want  to  see  the  data  in  a  particular  order. 
SORTing  a  database  file  is  equivalent  to  INDEXing  and  then 
copying  the  reorganized  data  to  a  new  file.  See  Language 
Reference  for  more  information  on  the  SORT  command. -ENDBOX- 

-H2-CREATING  INDEX  FILES 

When  you  INDEX  a  database  file,  dBASE  IV  creates  an  index  file 
containing  the  contents  of  the  key  expression  plus  a  pointer  to 
the  corresponding  record  in  the  database  file  (see  Figure  11-1) . 

-ILLUS-Figure  ll-l\mlndexing  a  database  file-ENDFIG- 


Index  files  help  you  produce  data  output  in  the  desired  order, 
conduct  more  efficient  searches,  and  establish  relations  between 
database  files. 

The  INDEX  command  creates  two  types  of  index  files.  Index  (.ndx) 
files  are  for  occasional  use  (say,  for  a  particular  report) . 
Multiple  index  (.mdx)  files,  on  the  other  hand,  are  for  routine 
or  production  use.  Each  multiple  index  file  can  include  up  to 
47  index  tags.  Each  tag  represents  a  separate  index  order.  You 
can  open  up  to  11  index  files  at  once,  including  the  multiple 
index  file. 
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dBASE  IV  maintains  a  special  multiple  index  file  that 
automatically  activates  the  indexes  you  want  to  keep  current  at 
all  times.  This  production  index  is  linked  to  the  database  file 
through  the  file  header,  has  the  same  root  name  as  the  database 
file,  and  opens  automatically  when  you  USE  the  database  file. 
dBASE  IV  guarantees  the  integrity  of  this  production  index  file. 

Tag  names  follow  the  same  naming  conventions  as  memory  variable 
names  (see  Chapter  3) .  To  define  the  production  index,  use  the 
TAG  option  and  omit  the  .mdx  filename: 

-M- INDEX  ON  Vendor_id  TAG  Vend_id-N- 

dBASE  IV  automatically  creates  the  production  index  if  none 
exists,  combining  the  root  name  of  the  database  file  with  the 
.mdx  extension. 

This  example  opens  the  Vendors  and  Goods  database  files  and 
creates  a  production  index  for  each.  The  Vendors  production  index 
contains  two  tags,  Vendor_id  and  Vendor  (vendor  name) .  The  Goods 
production  index  contains  three  tags,  Part_id,  Part_name,  and 
Vendor_id.  This  arrangement  lets  the  user  list  vendors  in  last 
name  order,  and  parts  by  either  name  or  identification  number.  It 
also  permits  the  programmer  to  relate  the  Vendors  and  Goods  files 
on  the  shared  Vendor  id  field. 
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-M-USE  Vendors-L- 

INDEX  ON  Vendor_id  TAG  Vendor_id-L~ 

INDEX  ON  Vendor  TAG  Vendor-L- 
SELECT  2-L- 
USE  Goods-L- 

INDEX  ON  Part_id  TAG  Part_id-L- 
INDEX  ON  Part_name  TAG  Part_name-L- 
INDEX  ON  Vendor_id  TAG  Vendor_id-N- 

Now  you  can  create  an  additional  multiple  index  file,  Mult2,  for 
the  Goods  database.  Mult2  contains  the  TAGS  Date_order  and  Cost. 
Because  it  is  not  the  production  index,  the  code  mentions  it 
explicitly  in  the  OF  clause.  Remember,  the  production  index  opens 
automatically  when  you  USE  the  database  file. 

-M-USE  Goods-L- 

INDEX  ON  Oate_order  TAG  Date_order  OF  Mult2~L~ 

INDEX  ON  Cost  TAG  Cost  OF  Mult2~N~ 

-H3-Controlling  Duplicate  Keys 

If  the  database  file  contains  more  than  one  record  with  the  same 
key  field  value,  INDEXing  the  file  with  the  UNIQUE  option 
includes  only  the  first  record  with  a  duplicate  key  field  in  the 
index  file.  UNIQUE  indexes  are  flagged  in  the  output  of 
DISPLAY/LIST  STATUS.  See  Language  Reference  for  examples  using 
UNIQUE. 
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"Checking  for  Duplication"  in  Chapter  9  provides  a  routine  that 
prevents  users  from  entering  duplicate  key  values. 

-H3-Indexing  in  Descending  Order 

The  DESCENDING  option  of  the  INDEX  command  indexes  an  expression 
in  reverse  order.  It  is  available  with  .mdx  tags  but  net  .ndx 
files.  This  option  affects  commands  that  move  the  record  pointer 
through  the  file,  such  as  BROWSE,  EDIT,  LIST,  and  SKIP. 

The  DESCENDING  option  aflects  all  the  fields  in  an  index  key 
expression.  This  example  indexes  the  Orders  database  file  in 
reverse  order  by  transaction  date  and  client  identification 
number : 

-M-USE  Orders-L- 

INDEX  ON  DTOS (Date_trans)  +  Client_id  TAG  Down  DESCENDTNG-N- 

You  can  also  index  a  numeric  or  date  field  in  descending 
order  in  combination  with  an  ascending  character  field.  The  code 
below  initializes  mmax_num  with  a  number  larger  than  any  the  user 
will  enter  into  the  Number  field.  Then  it  subtracts  Number  ‘ro» 
mmax_num.  Because  this  difference  decreases  as  the  value  of 
Number  increases,  INDEXiny  on  it  arranges  the  field  in  descending 
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order.  To  combine  the  descending  numeric  index  with  an  ascending 
character  index,  the  routine  concatenates  the  STR()  of  the 
difference  to  Char_fld. 

-H-mmax_num  =  1000-L- 

INDEX  ON  STR(minax_num  -  Number, 4,0)  +  Char_fld  TO  <f ilename>-N~ 

Follow  the  same  principle  to  index  a  date  field  in  descending 
order  in  combination  with  an  ascending  character  field: 

-M-mmax_date  =  { 12/12/2000 )-L- 

INDEX  ON  DTOS (mmax_date  -  Date_fld)  +  Char_fld  TO  <f ilename>-N- 


-H2-MODIFYING  INDEX  FILES 

You  can  modify  multiple  index  files  by  adding  or  deleting 
individual  index  tags. 

Adding  an  index  tag  is  similar  to  creating  the  multiple  index 
file.  This  example  adds  a  Zip_code  tag  to  the  Vendors  production 
index. 

-M-USE  Vendors-L- 

IND2X  ON  Zip_v  TAG  Zip_code-N- 
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Use  DELETE  TAG  to  delete  index  tags  from  multiple  index  files. 
Just  name  the  tag  you  want  to  delete,  and  the  multiple  index  file 
if  it's  not  the  production  index.  If  you  delete  all  the  tags  from 
the  production  index,  dBASE  IV  deletes  the  production  index  file 
and  updates  the  database  file  header  accordingly. 

-H2-USING  INDEX  FILES 


This  section  explains  how  to  use  index  files  in  your  application 
program.  Using  an  index  file  involves  opening  it,  closing  it,  and 
controlling  the  data  display  order. 

-H3-Opening  Index  Files 

You  should  weigh  two  conflicting  factors  in  deciding  which  index 
files  to  open  at  a  given  point  in  your  program: 

-o-All  index  files  that  you  want  to  keep  current  must  be  open 
whenever  the  user  adds  or  deletes  a  record,  or  modifies  a  key 
field. 

-o-Opening  many  index  files  at  once  slows  performance  when 
updating  the  database  file,  since  each  index  file  must  be 
updated . -ENDLIST- 
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As  a  rule  of  thumb,  open  index  files  only  as  you  need  them,  and 
REINDEX  to  make  them  currant.  You  can  open  up  to  7  .ndx  or  .mdx 
files  per  active  database  file.  Each  .mdx  file  can  contain  up  to 
47  tags.  By  using  the  two  types  of  index  files  judiciously,  you 
can  keep  the  number  of  open  index  files  to  a  minimum  yet  ensure 
that  essential  indexes  are  always  up-to-date.  This  maximizes  your 
application's  performance  without  sacrificing  database  integrity. 

To  open  a  file  with  a  production  index,  simply  USE  the  file. 

Since  the  file  header  for  the  database  file  identifies  the 
production  index,  you  don't  need  to  add  the  INDEX  clause. 

This  example  opens  the  Vendors  file  with  its  production  index  in 
work  area  1.  It  then  opens  the  Goods  database  file  with 
associated  production  and  alternate  multiple  index  files  in  work 
area  2.  It  ORDERS  the  Goods  display  by  order  date  in  the  second 
multiple  index  file. 

-M-USE  Vendors-L- 

USE  Goods  IN  2  ORDER  Date_order  OF  Mult2-N~ 

-H3~Closing  Index  Files 

A  variety  of  commands  handle  the  different  situations  in  which 
you  might  want  to  close  an  index  file.  Consult  Language  Reference 
for  more  information  on  the  individual  commands  named  here. 
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-o-DELETE  TAG  closes  one  or  more  index  (.ndx)  files  without 
closing  all  of  them.  DELETE  TAG  permanently  deletes  a  multiple 
index  tag  but  only  closes  an  .r.dx  file. 

-o-SET  INDEX  TO  with  a  file  list  closes  all  index  files  except 
the  production  index,  and  then  opens  the  index  files  named  in  the 
list. 

-o-SET  INDEX  TO  with  no  argument  or  CLOSE  INDEX  closes  all  open 
index  files  except  the  production  index. 

-o-To  close  the  production  index,  CLOSE  the  database 
file . -ENDLIST- 

-H3 -Control ling  the  Display  Order 

The  master  index  file  controls  the  display  and  search  order.  You 
can  specify  the  master  index  in  several  ways: 

-o-When  you  USE  the  database  file,  the  first-named  .ndx  file  or 
. mdx  tag  in  the  INDEX  file  list  or  ORDER  clause  is  the  master 
index. 

-o-If  the  database  file  is  already  in  USE,  SET  ORDER  TO  the 
desired  file  or  tag. 
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-o-If  the  database  file  is  already  in  USE  and  you  want  to  change 
the  active  index  files  and  the  display  order,  specify  the  new 
index  file  list  with  the  SET  INDEX  TO  command.  Include  an  ORDER 
clause  in  the  SET  INDEX  TO  syntax  or  place  the  desired  master 
index  file  first  in  the  file  list. 

-o-To  display  the  data  in  natural  (record  number)  order,  enter 
the  command  SET  ORDER  TO  0,  or  use  SET  ORDER  TO  or  SET  INDEX  TO 
with  no  argument.  The  latter  command  also  closes  all  open  index 
files  except  the  production  index. -ENDLIST- 

The  following  code  opens  the  Orders  database  file  and  indexes  it 
on  order  date  and  purchase  order  number.  The  index  is  a  TAG  in 
the  Reports  multiple  index  file. 

-M-USE  Orders-L- 

INDEX  ON  DTOS ( Date_trans )  +  PO_number  TO  TAG  Orders  OF  Reports-N- 

If  Orders  is  already  open,  use  the  SET  ORDER  command  to  make 
Orders  the  master  index: 

-H-SET  ORDER  TO  TAG  Orders-N- 

-H2 -DETERMINING  THE  CURRENT  INDEX  STATUS 
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The  DISPLAY  STATUS  command  and  several  functions  reveal  the 
current  index  status.  Table  11-1  summarizes  these  briefly. 
See  Language  Reference  for  more  detailed  information. 

-TABLE-Table  ll-l\mDetermining  index  status* 1 

Task 

List  all  active  index  files 
Return  name  of  specified  .ndx  file 
Return  name  of  specified  .mdx  file 
Return  name  of  specified  .mdx  tag 
Return  key  expression  of  .ndx  file  or  tag 
Return  name  of  master  .ndx  file  or  tag 


NOTE: 

1.  You  can  also  speci'fy  an  alias  with  the  functions  listed  in 
this  table. -ENDTABLE- 

The  routine  below  saves  the  current  database  filename  and  index 
order  before  it  CLOSES  all  database  and  index  files.  Then  it 
reopens  the  database  file  and  reestablishes  the  index  ORDER. 
Assume  that  the  ORDER  is  a  TAG  in  the  production  index. 

-M-mfilename  =  DBF()~L~ 
morder  =  ORDER ( ) — L— 


Command/  Function 

DISPLAY  STATUS 
NDX  ( ) 

MDX  ( ) 

TAG  ( ) 

KEY  ( ) 

ORDER () 
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CLOSE  DATABASES-L- 
USE  &mfilename-L- 
IF  ""  <>  morder-L- 

SET  ORDER  TO  TAG  &morder-L- 
ENDIF-N- 

-H2-ESTIMATING  THE  INDEX  FILE  SIZE 


The  following  routine  stores  the  size  of  the  index  file,  returned 
from  the  Ndxsize  procedure  below,  to  a  variable  called  indx_size. 
It  then  subtracts  the  index  size  from  DISKSFACE()  to  determine 
whether  there  is  enough  space  on  the  disk  for  the  index  file. 
Finally,  it  prompts  thd  user  to  change  disks  if  the  disk  space  is 
inadequate. 

-M-USE  Orders-L- 

STORE  0  TO  klength,  indx_size-L~ 

CLEAR- L~ 

mfield  =  SPACE(20)-L~ 

@  10,10  SAY  "On  what  field  do  you  want  to  index?  "  GET  mfield-L- 
READ-L- 

klength  =  LEN(TRIM(Smfield) )-L~ 

DO  CASE-L- 

CASE  TYPE  (infield)  =  "C"~L~ 
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klength  =  klength  +  MOD  (klength ,  4 )  -*L~ 

CASE  TYPE  (mfield)  =  "D"~L~ 
klength  =  8-L- 
CASE  TYPE  (mfield)  =■  "N"-L- 
klength  =  8-L- 
OTHERWISE-L- 

?  "Data  type  error"-L~ 

ENDCASE-L- 

DO  Ndxsize  WITH  klength,  indx_size-L- 
IF  DISKSPACE ( )  -  indx_size  <=  0-L- 
??  CHR(7)-L~ 

@  20,10  SAY  "Not  enough  space  on  disk  for  index  file"-L- 
@  22,15  SAY  "Change  disks  or  erase  files"-L- 
ENDIF-N- 


The  Ndxsize  procedure  estimates  the  size  of  an  .ndx  file  or  .mdx 
tag  to  within  an  accuracy  of  IK.  It  assumes  the  database  file  has 
just  been  INDEXed  or  REINDEXed.  (See  the  January  1987  issue  of 
TechNotes  for  an  explanation  of  this  procedure.) 

The  memory  variables  are  defined  as  follows: 

-o-keylength  —  number  of  characters  in  the  index  key  expression. 
Supplied  as  klength  from  the  previous  routine.  If  you'd  rather 
supply  the  value  yourself,  enter  8  for  numeric  or  date  type  keys, 
and  the  closest  multiple  of  4  (rounded  up)  for  character  keys. 


May  17,  1988 


Page  13 


Programming  with  dBASE  IV 


Ch.  11,  Ordering 

-o-keysperblk  —  number  of  index  keys  that  fit  in  one  512K  block. 
The  record  pointer  for  each  key  uses  8  bytes. 

-o-data_bloks  —  number  of  blocks  needed  for  all  keys. 

-o-totalbloks  —  total  number  of  blocks  needed  for  data  plus  the 
root  node  of  the  index  (2  blocks) -ENDLIST- 

-M-PROCEDURE  Ndxsize-L- 

PARAMETERS  keylength,  ndx_size~L~ 
keysperblk  =  INT(504  /  (keylength  +  8))~L~ 
data_bloks  =  RECCOUNT()  /  keysperblk- L~ 
totalbloks  =  data_oloks  +  2-L- 
keysperblk  =  keysperblk  +  l-L- 
DO  WHILE  data_bloks  >  keysperblk- L~ 

data_bloks  =  INT( (data_bloks  -  1)  /  keysperblk)  +  l-L- 
totalbloks  =  totalbloks  +  data_bloks-L- 
ENDDO-L- 

ndx_size  =  totalbloks  *  512-L- 
RETURN-N- 


-NOTE-The  size  of  .mdx  file  blocks  is  determined  by  the  value  of 
SET  BLOCKSIZE  when  the  index  file  is  created. -ENDBOX- 
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-HI- PROCESSING:  SEARCHING  FOR  DATA 


This  chapter  covers  the  programming  aspects  of  searching  for  data 
in  a  database  file.  You  use  the  same  commands  to  search  in  a 
program  as  you  do  to  search  at  the  dot  prompt.  However,  programs 
give  you  more  control  over  when  the  search  starts  and  stops. 

-H2-WHAT  THIS  CHAPTER  COVERS 


This  chapter  covers  the  following  topics: 

-o-Searching  for  single  records 

-o-Searching  for  multiple  records 

-o-Querying  database  files 
-o-Determining  whether  an  item  exists 

-o-Search  tips-ENDLIST- 

-COMMENT-The  Two  Search  Modes  and  Limits  of  the  File 

dBASE  uses  two  basic  search  modes.  Both  modes  follow  the  index 
order,  but  the  first  mode  searches  node  by  node,  while  the  second 
mode  uses  a  special  search  algorithm  to  quickly  reach  the 
specified  record  (see  Figure  12-1) . 
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-ILLUS-Figure  12-l\mThe  two  search  raodes-ENDFIG- 


Some  dBASE  IV  commands  and  functions  use  one  mode,  some  the 
other.  LOCATE  uses  the  first  method,  searching  the  index  file  if 
one  is  open,  otherwise  the  database  file.  LOOKUP() ,  like  LOCATE, 
searches  the  database  file  if  no  index  file  is  open.  FIND,  SEEK, 
and  SEEK()  use  the  second  method,  and  thus  require  an  index  file. 

As  you  review  the  examples  in  this  chapter,  keep  in  mind  that  the 
bottom  of  the  database  file  is  the  last  logical  record,  whereas 
the  end-of-file  (where  EOF()  is  .T.)  is  a  phantom  record  just 
after  the  last  logical  record.  The  top  of  the  file  is  the  first 
logical  record,  while  FOF()  is  set  to  .T.  when  you  try  to  access 
a  record  before  the  first  logical  record.  There  is  no  phantom 
record  at  the  beginning  of  the  file.-ENDCOM- 

-H2 -SEARCHING  FOR  SINGLE  RECORDS 


Often  a  user  wants  to  find  a  single  record  to  view  or  edit.  Your 
program  can  search  either  an  indexed  or  an  unindexed  file 
according  to  a  search  criterion  entered  by  the  user. 

-H3~Searching  an  Indexed  File 
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The  FIND  and  SEEK  commands  search  indexed  database  files  for 
records  with  the  specified  index  key  expression.  FIND  and  SEEK 
search  the  index  file,  using  a  search  algorithm  to  maximize  the 
search  speed.  Once  the  key  expression  is  found,  the  index  file 
points  to  the  corresponding  record  in  the  database  file. 

FIND  and  SEEK  are  similar  but  not  identical.  Table  12-1 
summarizes  their  major  differences. 


-TABLE-Table  12-l\mA  comparison 

FIND 

Used  mainly  at  dot  prompt 

Takes  a  literal  value: 

FIND  Smith 

Handles  character  expressions 
only: 

FIND  Dallas 

Hay  omit  delimiters: 

FIND  Los  AngelesCA1 
Use  &  (macro)  function  in 


of  FIND  and  SEEK 

SEEK 

Used  mainly  in  programs 

Takes  an  expression: 

SEEK  mlastname  +  mfirstname 

Handles  character,  numeric,  and 
date  expressions: 

SEEK  DATE()  -  Date_trans 

May  omit  delimiters  with 
numeric  data  only: 

SEEK  "Los  AngelesCA"1 

Use  variable  name  in  search  with 
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search  with  memory  variables 
FIND  Smcity . 


memory  variables: 
SEEK  mcity 


1.  Example  assumes  that  the  database  file  is  indexed  on 
City-State . -ENDTABLE- 

The  following  routine  shows  how  to  SEEK  a  single  record  in  a 
program.  Assume  that  Last_first  is  a  TAG  with  the  key 
expression  Lastname  +  Firstname.  If  the  user  presses  -RETURN- 
with  no  entry  (enters  a  null  string) ,  the  outer  IF  condition 
terminates.  If  the  user  enters  a  name,  the  routine  SEEKs  the  name 
and  prints  data  from  the  record  for  that  name. 

-M-USE  Employee  ORDER  Last_f irst-L- 
ACTIVATE  WINDOW  EE_win~L~ 

@  10,10  SAY  "Enter  last  name:  "  GET  Lastname-L- 
@  12,10  SAY  "Enter  first  name:  "  GET  Firstname-L- 
READ-L- 

DEACTIVATE  WINDOW  EE_win-L- 
IF  ""  <>  TRIM(Lastname+Firstname) -L- 
SEEK  TRIM(Lastname+Firstname) -L- 
IF  FOUND ()-L- 

?  Lastname,  Firstname,  Department,  Specialty-L- 
ENDIF-L- 
ENDIF-N- 
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The  next  example  is  based  on  the  Cust  database  file.  It  stores 
the  customer's  identification  code  in  the  memory  variable  code. 

It  then  SEEKs  and  LISTS  records  with  that  code  number. 

-M-USE  cust  ORDER  Cust_id-L- 
STORE  SPACE (6)  TO  code-L- 

@  10,10  SAY  "Enter  customer  code  "  GET  code  PICTURE  "!99999"~L- 
READ-L- 

SEEK  code  &&  Or  FIND  &code-L- 

LIST  Customer,  Phone,  Contact,  Date_iast  WHILE  Cust_id  =  code-N- 

-NOTE-FIND  and  SEEK  match  strings  starting  at  the  first  character 
and  continuing  only  until  a  match  occurs.  Thus,  dBASE  IV  might 
find  -R-Smith-I-  when  you're  looking  for  -R-Smithe-I- .  SET  EXACT 
ON  guarantees  an  exact  match  (see  -R-Language  Reference-I-)  .  Use 
SET  NEAR  to  keep  the  record  pointer  from  going  to  the  end  of  the 
file  if  a  search  fails. -ENDBOX- 

-H3-Searching  an  U.iindexed  File 

Use  LOCATE  to  search  an  unindexed  database  file.  To  make  a  LOCATE 
operation  as  fast  as  possible: 

-o-Put  large  database  files  in  natural  rather  than  indexed  order 
(SET  ORDER  TO  0)  before  doing  a  LOCATE.  Restore  the  index  order 
later  with  SET  ORDER  TO  <expN>/TAG. 
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-o-Use  the  <scope>  clause,  such  as  LOCATE  NEXT  5  FOR  Vendor_id  = 
“1000",  if  you  don't  want  the  search  to  start  at  the  top  of  the 
file. -ENDLIST- 

The  following  routine  LOCATES  a  particular  vendor  by  name.  Then 
it  BROWSEs  the  data  in  Vendor_id  order  starting  with  that  vendor. 

-M-USE  Vendors  ORDER  Vendor_id-L~ 

SET  ORDER  TO  0-L- 

LOCATE  FOR  Vendor  =  "Fastware  Furniture  Mfg."-L- 

SET  ORDER  TO  TAG  Vendor_id-L- 

BROWSE-N- 

-H2 -SEARCHING  FOR  MULTIPLE  RECORDS 

SCAN. . -ENDSCAN  is  a  programming  construct  that  processes  all  or 
selected  records  in  a  catabase  file.  It  works  with  both  indexed 
and  unindexed  files. 

The  following  example  displays  records  with  a  vendor  code  of  2100 
in  a  previously  defined  window.  It  displays  ten  records  at  a  time 
as  long  as  the  user  presses  any  key  to  continue,  until  the  end  of 
the  file. 

-M-USE  Goods  ORDER  Vendor_id-L- 
mvend_id  =  "2100"~L~ 

SEEK  mvend  id-L- 
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ACTIVATE  WINDOW  goods_win-L~ 

CLEAR-L- 

SCAN  ALL  WHILE  Vendorid  -  mvend_id-L~ 

LIST  OFF  NEXT  10  Part_id,  Partnama,  Cost  j-L- 
WHILE  Vendor_id  -  "2100"-L- 
WAIT  TO  answer-L- 
CLEAR-L- 
ENDSCAN-N- 

s can. . .ends can  is  particularly  useful  whan  you  want  to  run 
procedures  for  selected  records.  This  hypothetical  routine  scans 
an  unindexed  file  for  accounts  that  are  duo  today  and  havo  an 
outstanding  balance.  It  then  runs  a  separata  procedure  that 
prints  a  letter  for  each  matching  record. 

-M-SCAN  FOR  Due_date  -  DATE ( )  .AND.  Aat_due  >  0-L- 
DO  Letter  WITH  Lastname,  Firstname,  Amt_due-L- 
ENDSCAN-N- 

This  version  scans  the  same  file  indexed  on  Due_date: 

-M-SEEK  DATE()-L- 

SCAN  WHILE  Duejate  -  DATE  ( )  FOR  Asit_due  >  0-L- 

DO  Letter  WITH  Lastname,  Firstname,  Amt_due-L~ 

ENDSCAN-N- 
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-COMMENT- Previous  versions  of  dBASE  used  FIND,  SEEK,  or  LOCATE  in 
a  DO  WHILE  loop  to  scan  a  file.  The  example  just  shown  would  have 
been  coded: 

-M-SEEK  DATE()-L- 

DO  WHILE  Due_date  =  DATE ( )  .AND.  .NOT.  EOF()-L- 
IF  Amt_due  >  0-L- 

DO  Letter  WITH  Lastname,  Firstname,  Amt_due-L~ 

ENDIF-L- 

SKIP-L- 

ENDDO-N— ENDCOM- 

-H2 -SEARCHING  A  MEMO  FIELD 

dBASE  IV  allows  you  to  search  nemo  fields  and  extract  specific 
data,  using  AT ( )  or  SUBSTR()  with  a  routine  that  steps  through 
records.  For  example  the  following  code  finds  all  records  with 
the  word  patron  in  the  Notes  memo  field: 

-M-USE  <filename>~L~ 
to_find  =  "patron"-L- 
LOCATE  FOR  AT(to_find,  Notes)  <>  0-L- 
DO  WHILE  FOUND ()-L- 
?  Cust_id~L~ 

?  Notes-L- 
CONTINUE- L- 
ENDDO-N- 


May  17,  1988 


page  8 


Programming  with  dBASE  IV 


Ch.  12,  Searching 


-H2 -QUERYING  DATABASE  FILES 

You  can  query  a  database  file  for  fields  and  records  that  meet 
certain  conditions.  Formulate  queries  on  the  menu  system's 
queries  design  screen  (see  Using  the  Menu  System),  and 
incorporate  the  resulting  .qbe  file  into  your  program  code. 

Figure  12-2  shows  such  a  query,  alongside  the  corresponding  code. 

-ILLUS-Figure  12-2\mQuery  with  code-ENDFIG- 


You  can  also  build  queries  directly  from  dBASE  expressions.  This 
section  shows  some  examples.  If  you  aren't  familiar  with  the 
dBASE  operators,  see  Chapter  1  of  Language  Reference  before 
readirg  this  section. 

~H3~Simple  Queries 

A  simple  query  uses  one  condition.  Table  12-2  shows  some  simple 
queries  based  on  the  Employee  database  file. 

-TABLE-Table  12-2\mSimple  queries 

To  find  Query  expression 
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Employees  from 

USE  Employee  ORDER  State 

Nevada 

SEEK  "NV" 

LIST  Empid,  City,  Zip; 

WHILE  State  =  "NV" 

Exempt  employees 

USE  Employee 

LIST  OFF  Lastname,  Firstname,  ; 

Specialty  FOR  Exempt1 

Employees  hired  before  USE  Employee  ORDER  Date_hired 


June  1,  1988 

LIST  OFF  Lastname,  Firstname; 

FOR  Date_hired  <  (06/01/83) 

Employees  with  labor 

USE  Employee 

grade  other  than  2 

LIST  Lastname,  Firstname,  ; 

Laborgrade  FOR  Laborgrade  <>  "2" 

1.  Because  logical  fields  are  Boolean  (true/false) ,  the  field  is 
the  condition.  Thus,  you  don't  need  to  supply  an  expression.  Just 
use  FOR  Exempt  rather  than  FOR  Exempt  =  .T..~ ENDTABLE- 

-H3-Complex  Queries 
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A  complex  query  uses  more  than  one  condition  to  qualify  the 
database  file.  Table  12-3  shows  some  examples  based  on  the 
Employee  database  file. 

-TABLE-Table  12-3\mComplex  queries 


To  find 

Query  expression 

Employees  from  Nevada 

USE  Employee  ORDER  State 

or  Arizona 

LIST  Emp_id,  City,  State; 

FOR  State  =  "NV"  .OR.  State  =  "AZ" 

Exempt,  full-time 

USE  Employee 

employees 

LIST  OFF  Lastname,  Firstname,  ; 

Specialty  FOR  Exempt  .AND.  Full_time 

Employees  hired  between  USE  Employee  ORDER  Date_hired 


June  1,  1983  and 

LIST  OFF  Lastname,  Firstname; 

December  31,  1983, 

FOR  Date_hired  >=  (06/01/83); 

inclusive 

•AND.  Date_hired  <=  (12/31/83) 

Employees  with  labor 

USE  Employee 

grade  other  than  2  who 

LIST  Lastname,  Firstname,  Laborgrade; 

earn  less  than  $20,000 

FOR  Laborgrade  <>  "2"; 

•AND.  Salary  <  20000 

Employees  with  labor 

USE  Employee 
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grade  above  5,  without 
B.S.  or  B.A.  degree 


LIST  Lastname,  Firstname,  Degree; 

FOR  Laborgrade  >  "5"  .AND.  .NOT.; 
LIKE ( " B* " , UPPER ( Degree) ) -ENDTABLE- 


-H2 -DETERMINING  WHETHER  AN  ITEM  EXISTS 

Use  the  SEEK()  and  LOOKUP ()  functions  to  check  whether  an  item 
exists.  For  example,  if  your  program  doesn't  allow  duplicate  part 
numbers,  these  functions  can  check  the  user's  entry  against 
existing  part  numbers.  In  an  order  entry  system,  they  can  make 
sure  an  itsm  number  exists  before  your  program  processes  the 
order. 

Working  with  the  current  database  file,  SEEK()  returns  a  .T.  if 
the  search  expression  is  found  and  moves  the  record  pointer  to 
the  record  containing  the  string.  LOOKUP()  moves  the  record 
pointer  in  an  inactive  database  file  to  a  key  expression  matching 
the  one  in  the  current  file. 

This  first  example  uses  SEEKf)  to  print  vendor  names  and  phone 
numbers  for  a  vendor  code  of  1000: 

-M-USE  Vendors  ORDER  Vendor_id~L~ 
mvend_id  =  "lOOC-L- 
IF  SEEK(mvend_id,  Vendors) -L- 

LIST  WHILE  Vendor_id  =  mvend_id;-L- 
Vendor,  Phone_vend  OFF  TO  PRINT- L~ 
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ENDIF-N- 

The  following  LOOKUP ()  code  prints  the  part  name  and  quantity  on 
hand  from  the  Goods  file,  plus  the  name  of  the  vendor  from  the 
Vendors  database  file  (in  work  area  2),  for  records  with  a  vendor 
identification  code  of  2100. 

-M-USE  Goods  ORDER  Vendor_id-L- 
USE  Vendors  IN  2  ORDER  Vendor_id-L- 
mvend_id  ="2100"~L- 
SCAN  WHILE  Vendor_id  =  mvend_id-L~ 

?  Part_name,  Qty_onhand,  LOOKUP (Vendors->Vendor,  mvend_id, ;-L~ 
Vendors->Vendor_id) ~L~ 

ENDSCAN-N- 

-H2 -SEARCH  TIPS 


This  section  provides  some  tips  for  conducting  successful 
searches. 

Character  fields  often  end  in  varying  numbers  of  blank  spaces.  As 
a  rule  of  thumb,  if  the  last  part  of  an  expression  consists  of 
character  data,  TRIM()  it: 

-M-SEEK  TRIM  ( Part_name )  -11- 
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If  you're  searching  for  a  string  that  contains  leading  spaces, 
use  delimiters  with  macro  substitution.  This  example  finds  two 
leading  spaces: 

-M~m_item  =  "  sofa"  -L- 
FIND  "&m  item. "-N- 


When  you  concatenate  character  fields,  dBASE  inserts  blank  spaces 
between  the  fields  to  fill  up  the  field  width.  To  ensure  a 
successful  search,  initialize  memory  variables  with  the  defined 
field  width: 

-M-mf irstname  =  SPACE (LEN(Firstname) )~L~ 
mlastname  =  SPACE (LEN (Lastname) ) -L- 
@  10,10  SAY  "Enter  first  name:  "  GET  mf irstname-L- 
§  12,10  SAY  "Enter  last  name:  "  GET  mlastname-L- 
READ-L- 

SEEK  mlastname  +  mfirstname-N- 

To  eliminate  the  blanks  between  fields  entirely,  concatenate  them 
with  the  minus  (-)  operator: 

-M-INDEX  ON  Lastname  -  Firstname-L- 

FIND  NewmanRobert  &8No  space  between  names-N- 

(You  can  also  LIST  Lastname-Firstname . ) 
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To  search  on  fields  of  mixed  data  types,  convert  all  fields  to 
one  type.  (See  Chapter  10  for  more  information  on  the  data 
types . ) 

-M-USE  Orders-L- 

INDEX  ON  DTOS (Date_trans)  +  Cust_id  TAG  Cust_date-L- 
SEEK  DTOS ( DATE ( ) ) ~N~ 

Your  program  should  account  for  the  possibility  that  the  record 
being  sought  is  not  in  the  file.  You  can  test  for  a  failed  search 
in  three  ways: 

-o-Test  for  EOF():  dBASE  IV  positions  the  record  pointer  at  the 
end  of  the  file  when  a  search  fails  unless  SET  NEAR  is  ON. 

-o-Test  for  .NOT.  FOUND () 

-o-Test  for  .NOT.  SEEK()  (see  second  example  below) -ENDLIST- 

If  you  SET  NEAR  ON  before  conducting  the  search,  the  program  will 
stop  at  near  misses  when  a  FIND,  SEEK,  or  SEEK()  fails.  The 
record  pointer  stops  on  the  record  directly  following  the 
nonexistent  record  in  the  index  order. 
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The  following  routine  lets  users  guess  at  a  vendor  code.  It 
searches  Vendors  in  Vendor_id  ORDER  for  the  vendor  code  just 
after  the  guess.  Then  it  SKIPS  back  to  the  record  preceding  the 
guess  and  LISTs  the  two  flanking  records. 

USE  Vendors  ORDER  Vendor_id-L- 

@  10,10  SAY  "Enter  vendor  id:  "  GET  Vendor_id  PICTURE  "9999" ;-L~ 
MESSAGE  "Inexact  entries  OK.  Program  shows  closest  values."-L~ 
READ-L- 

SET  NEAR  ON-L- 
SEEK  Vendor_id-L~ 

IF  .NOT.  F0UND()-L- 
SKIP  -1~L- 
ENDIF-L- 

LIST  NEXT  2  &&  Can  also  use  BROWSE  or  @ . . . SAY. . . GET-N- 

This  routine  displays  a  message  if  the  vendor  number  is  not  found 
(if  SEEK()  returns  a  .F.).  Assume  that  mvend_id  stores  the  user's 
entry  of  a  vendor  number: 

-M-USE  Vendors  ORDER  Vendor_id-L- 
CLEAR-L- 

IF  .NOT.  SEEK(mvend_id)-L~ 

@  10,1  SAY  "Sorry,  there  is  no  "  +  mvend_id  +  ;-L~ 

"  in  the  file."~L- 
8  13,0-L- 
WAIT-L- 
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ELSE-L- 

*  <commands  to  process  vendor  no.  if  found>~L~ 
ENDIF-N- 
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-HI- PROCESSING:  RELATING  AND  RESTRICTING  DATA 

This  chapter  describes  how  your  program  can  refine  the  database 
environment  to  improve  the  power  and  efficiency  of  a  program. 

-H2-WHAT  THIS  CHAPTER  COVERS 

The  routines  discussed  here  allow  you  to  link  files  by  a  common 
field,  specify  which  fields  and  records  are  active,  and  capture 
the  environment  in  a  view  for  use  in  a  program.  Specifically,  the 
chapter  covers  the  following  topics: 

-o-Relating  database  files 

-o-Processing  selected  fields 

-o-Processing  selected  records 

-o-Working  with  views-ENDLIST- 

See  Chapter  1  of  Language  Reference  for  background  material 
related  to  this  chapter,  such  as  a  discussion  of  work. areas  and 
aliases. 

-H2 -RELATING  DATABASE  FILES 
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When  you  design  a  database  system,  you  create  separate  database 
files  to  avoid  redundancy  (see  Chapter  4) .  However,  you  might 
want  data  from  the  separate  files  to  appear  in  a  single  screen 
listing  or  printed  report.  The  SET  RELATION  command  lets  you 
relate  database  files  so  that  they  behave  almost  like  a  single 
file. 

-NOTE-The  query  design  screen  in  the  Control  Center  lets  you 
build  simple  relations  where  the  files  are  linked  on  a  single 
field  and  the  child  file  is  indexed  on  a  single  field  (see 
Chapter  7  of  Using  the  Menu  System) .  To  establish  more  complex 
relations,  use  the  programming  methods  shown  in  this 
chapter. -ENDBOX- 

-H3-About  Relations 

A  relation  is  a  link  between  two  or  more  database  files  based  on 
a  key  field  that  they  both  contain  (see  Figure  13-1).  Relations 
are  called  joins  in  database  theory.  The  primary  file  in  the 
relation  is  known  as  the  parent,  while  the  secondary  files  are 
the  children.  After  the  database  files  are  linked,  moving  the 
record  pointer  in  the  parent  file  moves  it  to  records  with  the 
same  index  key  expression  in  each  child.  Relations  are  generally 
used  to  link  many  records  in  a  child  to  one  record  in  a  parent. 

-ILLUS-Figure  13-l\mA  hypothetical  relation-ENDFIG- 
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zzzzzzz 
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05308 

zzzzzzz 

05308 

zzzzzzz 

05308 

zzzzzzz 

Before  establishing  a  relation,  decide  which  database  file  is  the 
parent  and  which  are  the  children.  For  example,  suppose  you  plan 
to  issue  a  report  showing  which  vendors  supply  which  articles  of 
furniture.  You'll  need  information  from  both  Vendors  and  Goods 
for  the  report;  however,  the  topic  of  the  report  is  vendors. 
Therefore,  Vendors  should  be  the  parent  file  in  this  relation, 
and  Goods  the  child. 

The  rest  of  this  section  shows  how  to  establish  different  types 
of  relations  within  a  program. 
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-NOTE- Always  move  the  record  pointer  after  a  SET  RELATION.  Any 
command  that  moves  the  record  pointer,  such  as  GO  RECNO() ,  GO 
TOP,  or  SKIP,  will  do.-ENDBOX- 

-H3-One-to-one  Relations 

A  one-to-one  relation  links  one  parent  file  to  a  single  child. 
This  type  of  relation  is  used  primarily  for  very  large  database 
file  structures  that  exceed  the  maximum  number  of  fields  (255) . 
For  example,  you  could  handle  a  500-question  marketing  survey  by 
relating  two  files,  each  containing  half  of  the  questions.  Figure 
13-2  shows  such  a  one-to-one  relation. 

-ILLUS-Figure  13-2\mA  one-to-one  relation-ENDFIG- 


|  Surveyl  | 


I 

v  KEY :  Survey_id 


|  Survey2  | 
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Here  is  the  code  to  set  up  this  hypothetical  relation: 


-M-SELECT  l-L- 
USE  Surveyl-L- 

USE  Survey2  ORDER  Survey_id  IN  2-L- 
SET  RELATION  TO  Survey_id  INTO  Survey2-L~ 

GO  TOP-N- 

-H3-One-to-many  Relations 

In  a  one-to-many  relation,  the  child  file  contains  several 
records  with  the  same  index  key  as  a  given  record  in  the  parent. 
In  the  example  shown  in  Figure  13-3,  each  vendor  supplies  several 
articles  of  furniture. 

-ILLUS-Figure  13-3\mA  one-to-many  relation-ENDFIG- 


|  Vendors  | 


I 

v  KEY:  Vendor  id 
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|  Goods  |  | 


Here  is  the  code  that  sets  up  this  relation.  The  SET  SKIP  command 
ensures  that  all  vendors  for  each  article  of  furniture  appear 
when  the  data  is  displayed  with  a  command  such  as  LIST  or  BROWSE. 
Without  SET  SKIP  in  the  code,  only  the  first  vendor  would  appear. 

-M-SELECT  1-L- 
USE  vendors-L- 

USE  Goods  ORDER  Vendor_id  IN  2-L- 
SET  RELATION  TO  Vendor_id  INTO  Goods-L- 
SET  SKIP  TO  Goods-L- 
GO  TOP-N- 

You  can  relate  files  in  series  to  build  a  relation  chain.  Figure 
13-4  shows  the  relation  chain  orders  ->  Goods  ->  Vendors,  which 
could  form  the  basis  of  an  order  form.  In  this  example,  a 
customer  can  order  several  items,  but  only  one  vendor  is  entered 
for  each  item  ordered. 

-ILLUS-Figure  13-4\mA  relation  chain-ENDFIG- 


May  17,  1988 


Page  6 


Programming  with  dBASE  IV 


Ch.  13,  R  &  R 


|  Orders 


I 

V  KEY:  Part  id 


Goods 


v  KEY:  Vendor  id 


|  Vendors  |  | 


-M-SELECT  1-L- 

USE  Orders  ORDER  Part_id-L- 

USE  Goods  ORDER  Part_id  IN  2-L- 

USE  Vendors  ORDER  Vendor_id  IN  3-L- 

SET  RELATION  TO  Part_id  INTO  Goods-L- 

SELECT  2-L- 
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SET  RELATION  TO  Vendor_id  INTO  Vendors-L- 
SELECT  1-L- 
SET  SKIP  TO  Goods-L- 
GO  TOP-N- 

-H3-Multiple  Child  Relations 

A  multiple  child  relation  links  one  parent  file  to  two  or  more 
children  (see  Figure  13-5)  .  The  following  routine  relates  one 
parent  file  with  three  children.  The  Orders  database  file  is 
related  to  Employee,  Goods,  and  Cust  in  work  areas  2,  3,  and  4, 
respectively.  Note  that  there  can  be  several  articles  of 
furniture  but  only  one  employee  and  one  customer  per  order. 

-ILLUS-Figure  13-5\mMuitiple  child  relation-ENDFIG- 


Orders  | 
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| Employee  |  |  Goods  |  |  |  Oust 


Here  is  the  code  that  sets  up  this  multiple  child  relation: 
-M-SELECT  1-L- 
USE  Orders-L- 

USE  Employee  ORDER  Emp_id  IN  2-L- 
USE  Goods  ORDER  Part_id  IN  3-L- 
USE  Oust  ORDER  Cust_id  IN  4-L- 
SET  RELATION  TO  Emp_id  INTO  Employee,  ;-L- 
Part_id  INTO  Goods,  Cust_id  INTO  Cust-L- 
SET  SKIP  TO  Goods-L- 
GO  TOP-N- 


-H3-Relating  a  File  to  Itself 

Suppose  you  have  a  Parts  database  file  with  the  same  structure  as 
Goods,  plus  a  Master_id  field.  The  Master_id  field  identifies  the 
main  assembly  part  of  which  the  sub-assembly  part  is  a  component. 
Every  part  in  the  system  has  a  part  number.  Parts  that  contain 
other  parts  also  have  a  master  part  number. 
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You  can  create  a  quick  bill  of  materials  for  this  system  by 
relating  the  Parts  file  to  itself  (see  Figure  13-6) .  This  is 
known  as  a  self-join  in  database  theory. 

-ILLUS-Figure  13-6\mA  bill  of  materials-ENDFIG- 


Here  is  a  hypothetical  routine  that  lets  users  look  up  the  master 
assembly  part  information  on  a  sub-assembly  part.  The  routine 
USEs  Parts  in  two  work  areas,  using  the  AGAIN  option  of  USE  in 
the  second  work  area. 

After  relating  the  file  to  itself,  the  routine  prompts  for  a  part 
to  look  up.  Then  it  initializes  mpart_id  with  the  entered  part 
number  and  SEEKS  this  number.  Finally,  it  displays  information 
about  the  master  assembly  part  or  tells  the  user  that  none 
exists. 

-M-SELECT  1-L- 

USE  Parts  ORDER  Part_id-L- 

USE  Parts  ORDER  Part_id  AGAIN  IN  2  ALIAS  Mastpart-L- 
SET  RELATION  TO  Part_id  INTO  Mastpart-L- 
@ . . . SAY  "Enter  part  number:  "  GET  mpart_id-L- 
READ-L- 

SEEK  mpart_id-L~ 
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IF  FOUND () -L- 

IF  ""  <>  TRIM(Mastpart->Mast_id) -L- 

?  "Master  part:  "  +  Mastpart->Part_id,  Mastpart->Cost,  ;~L~ 
Mastpart->Qty_onhand~L- 
ELSE-L- 

?  "There  is  no  master  assembly  part  for  this  item"~t,- 
ENDIF-L- 
ENDIF-N- 

-H3-Using  Relations 

Once  you've  set  up  a  relation,  use  it  in  programs  for  data  input 
and  output.  (See  Chapters  9  and  15  for  more  information  on  these 
topics. ) 

The  following  routine  builds  a  report  that  pulls  data  from 
several  related  database  files.  First  it  USEs  Orders,  Goods,  and 
Vendors  in  work  areas  1,  2,  and  3,  respectively,  and  relates  the 
three  files  in  a  chain.  Then  it  defines  the  report  date,  title, 
and  column  headings.  Finally,  it  prints  part  numbers  and  names 
from  Goods  and  vendor  numbers  from  Vendors,  grouped  by  customer 
number  from  Orders.  The  total  number  of  orders  prints  at  the  end 
of  the  report. 

-M-SELECT  1-L- 
mcount  =  0-L~ 

USE  Orders  ORDER  Order-L- 
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USE  Goods  ORDER  Part_id  IN  2-L- 
USE  Vendors  ORDER  Vendor_id  IN  3~L~ 

SET  RELATION  TO  Part_id  INTO  Goods-L- 
SELECT  2-L- 

SET  RELATION  TO  Vendor_id  INTO  Vendors-L- 

SELECT  1-L- 

GO  TOP-L- 

??  DATE()  AT  2-L- 

?-L- 

?  "ORDERS  GROUPED  BY  CUSTOMER  NUMBER"  AT  20-L- 
?-L~ 

?  AT  30  "Part  ID  Part  Name  Vendor  ID"-L- 
?  AT  30  "=======  =========  ========= »-l- 

DO  WHILE  NOT  EOF()-L- 
mcust_id  =  Cust_id~L~ 

?  mcust_id  AT  2-L- 

SCAN  WHILE  mcust_id  =  Cust_id-L- 

??  Goods->Part_id  AT  30,  Goods->Part_name  AT  40-L- 

??  Vendors->Vendor_id  AT  52-L- 

?-L~ 

mcount  =  mcount  +  1-L- 
ENDSCAN-L- 
ENDDO-L- 

??  "Total  no.  of  orders:  "  AT  2,  mcount  PICTURE  "99"  AT  23-N- 

The  next  example  shows  the  use  of  relations  in  a  data  input 
module. 
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The  first  portion  of  the  routine  USES  Orders,  Goods,  Employee, 
and  Oust  in  work  areas  1-4.  It  also  opens  a  Temp  file  in  area  5 
with  the  same  basic  structure  as  Orders. 

After  APPENDlng  10  BLANK  records  to  Temp,  the  program  gets  order 
information  from  the  user.  Information  that  need  only  be  entered 
once  is  READ  into  @. . .SAY. . .GETS;  A  Browse  window  controlled  by 
the  Entries  format  file  (shown  at  the  end  of  the  program) 
collects  the  variable  order  information.  Note  that  the  relation 
between  Temp  and  Goods  permits  the  calculated  fields  in  the 
BROWSE. 

Once  the  user  confirms  that  all  the  information  is  correct,  the 
program  REPLACES  fields  in  Oust,  Employee,  and  Orders.  Finally, 
it  APPENDS  the  part  number  and  quantity  from  Temp  into  Goods,  for 
all  non-blank  part  numbers. 


-M-CLEAR-L- 
SET  TALK  OFF-L- 

DEFINE  WINDOW  entries  FROM  9,20  TO  21,60-L- 
USE  Orders-L- 

USE  Goods  ORDER  Part_id  IN  2-L- 
USE  Employee  ORDER  Emp_id  IN  3-L- 
USE  Cust  ORDER  Cust_id  IN  4-L- 
USE  Temp  IN  5-L- 
SELECT  5-L- 
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SET  RELATION  TO  Part_id  INTO  Goods-L- 
GO  TOP-L- 

IF  RECCOONTO  >  0-L- 
ZAP-L- 
ENDIF-L- 
\m-L- 

cnt  =  l-L- 

DO  WHILE  cnt  <=  10-L- 
APPEND  BLANK- L- 
cnt  =  cnt  +  1-L- 
ENDDO-L- 
\m-L- 

DO  WHILE  .T.-L- 

@  10,10  SAY  "Enter  transaction  date:  "  GET  m->date_trans~L~ 
i  12,10  SAY  "Enter  employee  number:  "  GET  m->emp_id  ;-L- 
VALID  SEEK(Emp_id, "Employee") -L~ 

@  14,10  SAY  "Enter  customer  number:  "  GET  m->cust_id;  -L- 
VALID  SEEK ( Cust_id , "Cust") -L- 
@  16,10  SAY  "Enter  PO  number:  "  GET  m->PO_number~L~ 

READ-L- 

SET  FORMAT  TO  Entries-L- 

BROWSE  NODELETE  COMPRESS  FORMAT  WINDOW  entries  ;~L~ 

FIELDS  Part_id,  Part_qty,  p_name  =  Goods->Part_name,  ;-L- 
p_quant  =  (Part_qty  -  Goods->Qty_onhand) -L- 
CLOSE  FORMAT-L- 
done  =  ""-L- 

@  21,20  SAY  "Is  all  data  correct?  (Y/N/Exit)"  ;-L- 
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GET  done  DEFAULT  "Y"  PICTURE  " !  '•  VALID  done  $  "YN"-L~ 
READ-L- 

IF  done  $  "YE"~L~ 

IF  done  =  "Y"-L~ 

REPLACE  ALL  Cust_id  WITH  m->cust_id,  Emp_id  WITH  ;~L~ 
m->emp_id,  Date_trans  WITH  m->date_trans,  ;-L- 
PO_number  WITH  m->PO_number-L~ 

SELECT  1-L- 

APPEND  FROM  Temp  FOR  <>  TRIM (Part_id) -L~ 

ENDIF-L- 
EXIT-L- 
ENDIF-L- 
ENDDO-L- 
CLEAR  WINDOW-L- 
RETURN-L- 
\m-L- 

*Entries . fmt-L- 
@  1,1  GET  Part_id~L~ 

@  1,20  GET  Qty  DEFAULT  0  WHEN  (""  <>  TRIM(Part_id) ) ;-L- 
VALID  IF  ""  =  TRIM ( Part_id )  ;-L~ 

ERROR  "You  must  enter  a  part  number  first"-N- 

-H2 -PROCESSING  SELECTED  FIELDS 


The  SET  FIELDS  command  lets  you  specify  which  fields  you  want 
dBASE  IV  to  process  and  in  what  order.  (This  is  called  a 
projection  in  database  theory.)  SET  FIELDS  affects  any  command 
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that  allows  you  to  specify,  a  field  list,  including  BROWSE,  EDIT, 
and  LIST.  Unlike  previous  versions  of  dBASE,  dBASE  IV  maintains  a 
single  field  list  for  all  work  areas. 

SET  FIELDS  is  really  two  commands:  SET  FIELDS  TO  <field  list>  and 
SET  FIELDS  on/OFF.  When  you  SET  FIELDS  TO  a  field  list,  you 
automatically  SET  FIELDS  ON.  If  you  no  longer  want  the  field  list 
to  be  in  effect,  SET  FIELDS  OFF  in  your  program. 

SET  FIELDS  TO  is  additive,  so  each  new  instance  of  the  command 
adds  fields  to  the  existing  list.  The  only  way  to  delete  fields 
from  the  list  is  to  delete  the  field  list  (SET  FIELDS  TO  with  no 
argument,  or  CLEAR  FIELDS) . 

The  following  code  specifies  an  active  field  list  from  Vendors: 

-M-USE  Vendors-L- 

SET  FIELDS  TO  Vendor,  Addressl_V,  C.ty_V,  State_V,  Zip_V-L- 

BROWSE-L- 

SET  FIELDS  OFF-N- 

To  include  fields  from  other  work  areas,  open  the  files  in  their 
respective  work  areas  but  SET  FIELDS  TO  from  the  current  area. 
Precede  the  names  of  fields  from  other  work  areas  with  the  proper 
ALIAS.  Note  the  use  of  a  calculated  field  in  the  following  field 
list: 
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-M-USE  Goods  ORDER  Part_id~L~ 

USE  Vendors  ORDER  Vendorid  IN  2-L- 
SET  RELATION  TO  Vendor_id  INTO  Vendors-L- 
SET  FIELDS  TO  Part_id,  Part_name,  Qty_onhand ,  Cost,  ;-L~ 
total_cost  =  Qty_onhand*Cost,  Vendors->Vendor-L~ 

BROWSE-L- 

SET  FIELDS  OFF-N- 

With  dBASE  IV,  you  can  use  the  standard  DOS  wildcards  to 
represent  a  field  list.  Here's  the  first  example  in  this  section, 
modified  to  use  wildcards: 

-M-USE  Vendors-L- 

SET  FIELDS  TO  Vendor-L- 

SET  FIELDS  TO  ALL  LIKE  *_V  ADDITIVE-L- 

BROWSE-L- 

SET  FIELDS  OFF-N- 

-H2-PROCESSING  SELECTED  RECORDS 

Sometimes,  you  only  want  to  see  certain  data  on  the  screen  or  in 
a  report.  For  example,  you  might  only  want  records  for  a 
particular  vendor,  from  a  particular  state,  or  for  a  particular 
range  of  dates. 
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Filtering  a  database  file  creates  a  temporary  subset  of  the 
complete  file.  (A  filter  is  called  a  selection  in  database 
theory.)  Use  SET  FILTER  to  include  records  that  meet  a  filter 
condition,  and  SET  DELETED  to  exclude  records  slated  for 
deletion. 

-H3 -Including  Matching  Records 

SET  FILTER  lets  you  specify  a  condition  that  a  record  must  meet 
to  be  included  in  the  filtered  database  file.  SET  FILTER  filters 
records  in,  not  out.  Some  typical  filter  expressions  are: 

-o-SET  FILTER  TO  State  =  "CA" 

-o-SET  FILTER  TO  State  =  "CA"  .AND.  Zip  <  "91400" 

-o-SET  FILTER  TO  Date_order  =  DATE ( ) 

-o-SET  FILTER  TO  Date_trans  >  iudate  .AND.  Date_trans  <  mdate  +  30 
-ENDLIST- 


-NOTE-Always  move  the  record  pointer  after  a  SET  FILTER.  Any 
command  that  moves  the  record  pointer,  such  as  GO  RECNO(),  GO 
TOP,  or  SKIP,  will  do.-ENDBOX- 


May  17,  1988 


Page  18 


Programming  with  dBASE  IV 


Ch.  13,  R  &  R 


The  following  code  selects  employees  with  more  than  five  years  of 
experience  who  are  earning  less  than  $25,000  per  year.  The  GO  TOP 
positions  the  record  pointer  at  the  first  matching  record.  The 
last  line  removes  the  filter  so  that  it  does  not  affect 
subsequent  operations. 

-M-USE  Employee  ORDER  Years-L- 

SET  FILTER  TO  Yrs_exper  >  5  .AND.  Salary  <  25000-L- 
GO  TOP-L- 
IF  .NOT.  EOF ( ) -L- 

LIST  OFF  Lastname,  Firstname,  Yrs_exper,  Salary-L- 
ELSE-L- 

?  "No  records  meet  the  filter  condition"-L- 
ENDIF-L- 

SET  FILTER  TO-N- 

The  filter  condition  in  the  next  routine  contains  a  calculated 
character  field.  See  "Relating  Database  Files"  earlier  in  this 
chapter  for  more  information  on  SET  RELATION. 

-M-USE  Orders-L- 

USE  Goods  ORDER  Part_id  IN  2-L- 

SET  RELATION  TO  Part_id  INTO  Goods-L- 

SET  FILTER  TO  Invoiced  .AND.  Goods->Part_name  =  "BOOKCASE"-N~ 
Variation  —  Filtering  Large  Files 
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Working  with  a  very  large  fila  is  often  more  efficient  if  you 
create  a  temporary  processing  file  containing  only  the  desired 
records.  This  timesaver  only  works  if  you  are  viewing  or  printing 
the  file,  not  editing  it. 

One  way  to  do  this  is  through  the  SORT  command: 

-M-SORT  TO  Underpaid  ON  Yrsexper ,  Salary  FOR  Yrs_exper  >  5;-L- 
•AND.  Salary  <  25000-L- 
USE  Underpaid-N- 

Another  way  is  to  first  INDEX  the  file  and  then  COrY  the  desired 
records  to  another  file: 

-M-INDEX  ON  STR(Yrs_exper,n,n)  +  STR(Salary,n,n)  TO  Underpaid-L- 
SEEK  "  5''-L- 

COPY  TO  Underpaid  FOR  Yrs_exper  >  5  .AND.  Salary  <  25000-L- 
WHILE  Yrs_exper  =  5-N- 

The  following  routine  might  be  used  to  archive  a  large  file.  The 
COPY  condition  selects  records  for  employees  hired  three  or  more 
years  ago.  The  LEFT ( )  function  extracts  the  month  and  year  as 
character  data.  The  RIGHTO  function  extracts  the  last  two 
characters,  converts  them  to  a  year,  and  subtracts  3.  Finally, 
the  condition  concatenates  the  two  strings  and  converts  them  back 
to  a  date,  using  curly  braces  instead  of  CTOD(). 
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-M-USE  Employee  ORDER  Date_hired-L~ 

COPY  TO  Archive  WHILE  Date_hired  <=  (LEFT(DTOC (DATE ( ) ) , 6)  +  ;-L- 
RIGHT ( STR ( YEAR ( DATE ( ) )  -  3,4),2))~N~ 

-H3 -Excluding  Deleted  Records 

If  SET  DELETED  is  ON  in  your  program,  records  marked  for  deletion 
are  excluded  in  many  operations  (see  Language  Reference  for  more 
detail) .  Programmers  usually  SET  DELETED  ON  in  the  program  setup 
area  (see  Chapter  6) ,  rather  than  within  the  body  of  the  program 
as  this  code  fragment  suggests. 

-M-USE  Employee  ORDER  Employee-L- 
SET  DELETED  ON-L- 

LIST  Lastname,  Firstname,  Phone_emp-L- 
SET  DELETED  OFF-N- 


You  might  also  want  to  SET  DELETED  ON  when  you  want  to  COPY  only 
active  records  TO  a  new  database  file. 

-H2-WORKINC  WITH  VIEWS 

You  can  define  a  view  file  that  assembles  one  or  more  database 
files  and  their  ancillary  files  (forms,  reports,  and  indexes). 
Opening  the  view  file  opens  all  the  component  files  and 
establishes  the  necessary  relations. 
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-H3-Creating  a  View 

dBASE  IV  lets  you  create  two  types  of  views:  .qbe  views  (defined 
on  the  queries  design  screen)  and  .vue  views  (defined  at  the  dot 
prompt) .  Each  type  of  view  has  its  own  advantages: 

-o-You  can  use  .qbe  views  to  specify  complex  relations, 
calculated  fields,  and  aggregate  operators  without  programming. 

-o-You  can  generate  dBASE  code  from  .qbe  views. 

-o-You  can  SET  FORMAT  TO  a  screen  format  file  in  a  .vue 
view . -ENDLIST- 

Using  the  Menu  System  describe  how  to  define  views  on  the  queries 
design  screen  (accessed  through  the  menu  system) .  Figure  13-7 
shows  a  typical  query  definition,  along  with  the  code  generated 
by  the  processor  for  that  query. 

-NOTE-When  you  TYPE  a  .qbe  file,  you  see  only  the  dBASE  code  at 
the  top  of  the  file.  The  file  also  contains  internal  code  for  the 
queriy  processor,  but  you  cannot  TYPE  this  code.  There  is  a 

-CONTROL - Z-  character  between  the  two  parts  of  the 

file. -ENDBOX- 

-ILLUS-Figure  13-7\mQuery  definition  with  code-ENDFIG- 
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You  create  views  at  the  dot  prompt  by  typing  the  component 
commands  and  then  entering  CREATE  VIEW  FROM  ENVIRONMENT. 

-NOTE-You  can  convert  .vue  views  to  .qbe  views  using  the  command 
MODIFY  QUERY  c.vue  filenames  However,  the  SET  RELATION  command 
will  not  be  represented  on  the  query  design  screen.  You  will  have 
to  set  up  the  links  again  in  the  query  processor . -ENDBOX- 

-H3-Using  a  View  in  a  Program 

You  don't  open  a  view  as  a  distinct  entity.  Rather,  you  activate 
a  view,  which  opens  the  files  in  the  view.  Activate  a  view  in  a 
program  in  one  of  the  following  ways: 

-o-Create  the  view  on  the  queries  design  screen.  In  your  code, 

SET  VIEW  TO  c.qbe  view>. 

-o-Create  the  view  at  the  dot  prompt.  In  your  code,  SET  VIEW  TO 
<.vue  view>. 

-o-Create  the  view  in  your  program  code  directly  by  putting  the 
commands  that  define  the  view  into  a  procedure  file.  DO  the 
procedure  when  you  want  to  activate  the  view. 
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-o-Create  the  view  on  the  queries  design  screen.  Edit  a  copy  of 
the  resulting  .qbe  file  in  MODIFY  COMMAND.  Make  any  desired 
modifications,  and  put  the  resulting  code  in  your 
program. -ENDLIST- 

The  first  two  methods  call  external  view  files  and  thus  save  some 
lines  of  code  in  your  program.  Put  the  SET  VIEW  command  in  the 
program  setup  area  (see  Chapter  6) .  The  last  two  methods 
incorporate  the  view  code  directly  into  your  program,  so  it 
needn't  call  an  external  program  file.  These  methods  ensure  that 
the  view  code  is  always  available,  aid  might  also  make  your 
program  run  a  bit  more  quickly. 

You  don't  close  a  view  directly  when  you  no  longer  want  it  to  be 
in  effect.  Just  close  the  files  in  the  view  with  CLOSE,  CLOSE 
DATABASES,  or  CLEAR  ALL. 

-H3-Editing  and  Deleting  Records  in  a  Multi-file  View 

If  your  program  uses  a  view  that  relates  two  or  more  database 
files,  editing  or  deleting  data  becomes  a  bit  more  complicated. 
You  must  address  two  fundamental  issues  in  your  program  design: 

-o-When  the  user  edits  or  deletes  a  record,  should  the 
parents/children  of  that  record  also  be  added  to  or  deleted? 
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-o-When  the  user  edits  or  deletes  a  record,  are  the  contents  of 
the  primary  key  field  still  unique?-ENDLIST- 

The  next  two  examples  in  this  chapter  respond  to  the  first 
question.  See  "Checking  for  Duplication"  in  Chapter  9  for  a 
discussion  of  the  second  issue. 

Do  a  cascading  DELETE  to  ensure  that  the  parents/children  of  a 
record  are  DELETEd  along  with  the  record.  This  example  DELETES  a 
customer  from  the  Cust  database  file  and  all  orders  placed  by 
that  customer  from  Orders.  Remember  to  PACK  database  files 
periodically  (see  "Deleting  Data  from  the  Database"  in  Chapter 
9). 

-M-USE  Cust  ORDER  CUSt_id-L- 
USE  Orders  ORDER  Cust_id  IN  2~L~ 

SET  RELATION  TO  Cust_id  INTO  Orders-L- 

@ . . . SAY  "Enter  ID  of  customer  to  be  deleted:  "  GET  mcust_id-L- 
READ-L- 

IF  SEEK(mcust_id)-L~ 

DELETE-L- 
SELECT  2-L- 

DELETE  ALL  WHILE  mcust_id  =  Cust_id  -L~ 

SELECT  1-L- 
ELSE-L- 

WAIT  "Customer  ID  not  found. "-L- 
ENDIF-N- 
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The  following  routine  does  a  cascading  edit.  Note  that  this 
method  does  not  permit  the  user  to  update  the  key  field.  First  it 
USEs  Cust  and  Orders  in  their  respective  work  areas  and  relates 
them.  The  SET  SKIP  command  ensures  that  all  orders  display  for 
each  customer. 

Then  the  code  prompts  the  user  for  a  customer  number.  The  routine 
terminates  if  the  user  enters  a  null  (presses  -RETURN-)  and 
displays  messages  if  the  customer  number  isn't  in  Cust,  or  if 
there  are  no  orders  for  that  customer  in  Orders.  The  ?  INKEY () 
command  pauses  the  program  until  the  user  presses  a  key. 

Next,  the  routine  GETS  the  Customer  and  Part_qty  fields  from  the 
two  files  and  lets  the  user  edit  them.  The  CASE  statement  LOOPS 
out  of  the  subroutine  when  the  user  finishes  editing,  or  SKIPs 
the  record  pointer  forward  or  backward  at  the  user's  request.  It 
uses  READKEY ( )  instead  of  LASTKEY ( )  in  case  other  keys  are 
assigned  full-screen  exit  values,  such  as  SET  FUNCTION  F2  TO 
CHR(27) . 

If  the  user  pages  down  or  up  to  a  record  with  a  different 
customer  number,  the  routine  restores  the  record  pointer  (SKIP 
(MSKEP  *  -1) )  and  tells  the  user  that  there  are  no  more  orders 
for  the  customer  entered  previously. 
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-M-USE  Oust  ORDER  Cust_id-L- 
USE  Orders  ORDER  Cust_id  IN  2-L~ 

SET  RELATION  TO  Cust_id  INTO  Orders-L- 

SET  SKIP  TO  Orders-L- 

\m-L- 

DO  WHILE  .T.-L- 

mcust_id  =  SPACE (8) -L- 

S...SAY  "Enter  customer  ID:  "  GET  mcust_id-L~ 

READ-L- 

IF  »»  =  TRIM(racust_id)-L- 
EXIT-L- 
ENDIF-L- 

IF  .NOT.  SEEK (mcust_id) -L- 

@ . . . SAY  "Customer  ID  not  found.  Press  any  key."-L- 
?  INKEY (OJ-L- 
LOOP-L- 
ENDIF-L- 

IF  mcust_id  <>  Orders->Cust_id-L- 

0...SAY  "No  orders  exist  for  that  ID.  Press  any  key."-L~ 
?  INKEY(0)-L- 
LOOP-L- 
ENDIF-L- 
\m-L- 

order_ok  =  .T.-L- 
DO  WHILE  order_ok-L- 
@ . . .GET  Customer- L- 
8... GET  Order s->Part_qty-L- 
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READ-L- 
DO  CASE-L- 

CASE  STR ( READKEY ( ) , 3 )  $  "  12,270"-L- 
order_ok  =  . F.-L- 
LOOP-L- 

CASE  STR (READKEY ( ) , 3)  $  "  1,257,  5,261,  7,263,  15,271 

mskip  =  1-L- 

CASE  STR (READKEY (), 3 )  $  "  0,256,  4,260,  6,262"-L- 

mskip  =  -1-L- 
ENDCASE-L- 
SKIP  mskip-L- 
@  20,1  SAY  SPACE ( 10) -L- 
IF  mcust_id  <>  Cust_id-L- 

SKIP  (mskip  *  -1)-L- 

§  20,1  SAY  "No  more  orders  for  the  customer  ID  you  enter 
ENDIF-L- 


ENDDO-L- 


ENDDO-L- 


RETURN-N- 
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-Hl-DATA  SECURITY  AND  INTEGRITY 

Users  of  your  applications  should  have  confidence  that  their  data 
is  secure  against  loss  or  corruption,  and  that  it  is  in  a 
consistent  state  throughout  the  application.  This  chapter  reviews 
some  techniques  for  handling  disk  files  from  within  a  program, 
and  then  shows  how  your  programs  can  ensure  the  security  and 
integrity  of  the  data  they  handle. 

-H2-WHAT  THIS  CHAPTER  COVERS 

This  chapter  discusses  the  following  topics: 

-o-Handling  disk  files 

-o-Backing  up  data 

-o-Managing  data  transactions 

-o-Protecting  data-ENDLIST- 

The  last  two  topics  are  only  summarized  here,  because  they  are 
covered  in  detail  in  networking  with  dBASE  IV.  The  section 
"Checking  Data  for  Errors"  in  Chapter  9  of  this  book  discusses 
ways  of  preventing  data  entry  errors. 

-H2 -HANDLING  DISK  FILES 

You  can  perform  many  disk  file-handling  operations  from  within  a 
dBASE  IV  program.  This  section  reviews  how  a  program  can  identify 
and  find  files,  delete  files,  import  and  export  files,  and 
determine  file  size  and  available  disk  space. 

-H3~Identifying  a  Database  or  Index  File 

The  DBF ( )  function  returns  the  name  of  the  database  file  in  USE, 
if  any.  To  identify  the  open  database  file  in  an  unselected  work 
area,  provide  the  alias  with  the  function.  DBF()  returns  a  null 
string  if  no  file  is  in  USE  in  the  specified  work  area. 

Use  the  following  short  routine  to  close  all  files  except  the 
database  file  in  the  current  work  area.  The  routine  first  stores 
the  name  of  the  current  database  file  to  m filename .  Then  the 
CLOSE  ALL  command  closes  all  open  database  files  and  associated 
index,  format,  and  memo  files,  but  does  not  release  memory 
variables.  Finally,  the  routine  reopens  the  database  file  noted 
in  mfilename. 

-M-mfilename  =  DBF()-L- 

CLOSE  ALL-L- 

USE  Smfilename.-N- 

The  MDX( )  and  NDX()  functions  return  the  name  of  an  open  index 
file  in  the  specified  work  area  (see  Chapter  11) . 

-H3-Finding  Files 
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Usually  an  application  accesses  files  directly  without  the  user's 
knowledge.  Sometimes,  however,  a  program  must  request  a  filename 
from  the  user.  In  that  case,  use  the  FILES  option  of  DEFINE  POPUP 
to  display  a  file  directory. 

The  following  module  displays  a  list  of  database  files.  First, 
DEFINE  POPUP  defines  the  file  list.  Note  that  the  LIKE  *.dbf 
clause  limits  the  display  to  database  files.  Then  the  routine 
ACTIVATES  the  list  and  stores  the  user's  file  selection  to  m file. 
If  the  user  presses  -RETURN-  without  selecting  a  file,  a  message 
appears  and  the  routine  ends.  Otherwise,  the  routine  opens  the 
selected  file. 

-M-DEFINE  POPUP  filespop  FROM  4,30  PROMPT  FILES  LIKE  *.dbf  ;-L- 
MESSAGE  "Press  <Enter>  to  select  a  file"-L- 
ACTIVATE  POPUP  filespop-L- 
mfile  =  PROMPT ( )-L- 
IF  ""  =  mfile-L- 

@  21,  30  SAY  "No  file  selected"-L~ 

WAIT  "Press  any  key  to  return  to  Main  Menu"-L- 
RETURN-L- 
ENDIF-L- 
USE  Smfile.-L- 
RELEASE  POPUP  filespop-N- 

You  can  use  a  similar  routine  to  locate  files  of  another  type. 
Just  change  the  file  skeleton  in  the  DEFINE  POPUP  statement  and 
replace  the  USE  command  with  the  appropriate  command. 

~H3~Deleting  Files 

Usually  an  application  deletes  files  automatically.  If  you  want 
your  program  to  prompt  users  for  files  to  delete,  define  a  file 
list  as  shown  in  the  previous  section.  Use  the  same  code,  but 
replace  the  USE  commard  with: 

-M- ERASE  Smfile.-N- 

If  you  want  to  use  wildcards  to  delete  groups  of  similarly  named 
files,  use  the  DOS  ERASE  command  instead  of  dBASE  ERASE: 

-M-RUN  ERASE  *.txt-N- 

-H3 -Importing  and  Exporting  Files 

Complex  microcomputer  applications  typically  store  data  in  a 
specific  format  that  is  foreign  to  other  applications.  For 
example,  dBASE  IV  stores  information  about  a  database  file  in  the 
database  file  header. 

Your  programs  might  have  to  import  files  that  are  in  another  file 
format,  or  export  files  to  another  format.  dBASE  IV  can  read  a 
number  of  foreign  file  formats  directly.  For  example,  you  can 
IMPORT  and  EXPORT  PFS : FILE-TR- ,  Framework  II-TR-,  RapidFile-TM- , 
dBASE  II-TR-,  and  Lotus  1-2-3-TR-  (WK1)  file  formats.  You  can 
also  APPEND  FROM  and  COPY  TO  the  formats  just  mentioned,  as  well 
as  VisiCalc-TR-  (DIF),  MultiPlan-TR-  (SYLK) ,  and  Lotus  1-2-3-TR- 
(WKS)  file  formats. 
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To  import  a  foreign  file  that  dBASE  IV  cannot  read  directly,  you 
must  convert  the  data  into  a  format  that  dBASE  IV  understands. 
Use  the  original  application  to  strip  out  the  superfluous  format 
information  and  create  an  ASCII  text  file  with  either  fixed 
length  records  (SDF)  or  delimited  fields.  (Most  applications 
provide  this  capability.)  Then  import  the  raw  data  into  existing 
database  files,  using  APPEND  FROM  with  the  DELIMITED  WITH  or  SDF 
option. 

See  Language  Reference  for  more  information  on  IMPORT,  EXPORT, 
APPEND  FROM,  and  COPY  TO. 

-H3-Determining  File  Size  and  Disk  Space 


Sometimes  the  action  taken  by  your  program  depends  upon  the  size 
of  the  database  file  and  the  available  space  on  disk.  For 
example,  your  programs  should  check  for  sufficient  disk  space 
before  SORTing  or  Copying  a  database  file. 

This  section  provides  two  user-defined  functions  (UDFs)  that 
determine  the  size  of  database  and  memo  files,  and  then  shows  how 
to  use  the  information  in  a  routine  that  determines  available 
disk  space. 

-H4~Computing  database  (.dbf)  file  size 

The  following  UDF  computes  the  total  size  of  a  database  (.dbf) 
file.  First  it  opens  the  file  passed  to  it  from  the  calling 
module  (see  "Determining  Available  Disk  Space"  below) .  Then  it 
computes  the  total  record  volume  by  multiplying  RECCOUNT()  by 
RECSIZE ( ) . 

Next,  the  routine  uses  a  DO  WHILE  loop  to  count  the  fields  in  the 
database  file.  Each  pass  through  the  loop  increments  field_no  by 
one.  Then  FIELD()  returns  the  name  of  the  field  denoted  by  that 
number.  When  there  are  no  more  fields,  FIELD (fieldjno  +  1) 
returns  a  null  string  and  the  loop  ends.  The  value  of  field_no, 
which  is  the  number  of  fields  in  the  file,  is  assigned  to 
nu mfields . 

The  last  part  of  the  routine  uses  a  formula  to  compute  the  size 
of  the  database  file  header.  (dBASE  maintains  a  file  header  that 
keeps  track  of  field  names,  lengths,  and  types.)  Then  it 
calculates  the  total  size  of  the  database  file.  This  consists  of 
the  record  volume,  the  header  size,  plus  one  byte  for  an 
end-of-file  marker 

-M- FUNCTION  Dbf  size-L- 
PARAMETERS  mfile-L- 
USE  Smfile. -L- 

rec_vol  =  RECCOUNTf)  *  RECSIZE ()-L~ 

\m-L- 

field  no  =  0-L- 

DO  WHILE  ""  <  FIELD (field  no  +  1)-L- 
field_no  =  field_no  +  T-L- 
ENDDO-L- 
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numfields  =  field  no-L- 
\m-L- 

header  =  (32  *  numfields)  +  34-L- 

dbf_size  =  rec_vol  +  header  +  l-L- 
RETURN  dbf_size-N- 

-H4-Computing  memo  (.dbt)  file  size 

The  UDF  shown  here  obtains  the  size  of  a  memo  (.dbt)  file  from 
the  DOS  directory  listing.  (You  can  use  this  same  method  to 
determine  the  size  of  any  type  of  file.)  The  first  part  of  this 
UDF  creates  an  empty  database  file.  It  opens  Oust  (any  database 
file  will  do)  and  copies  its  structure  to  Temp.  (COPY  STRUCTURE 
EXTENDED  creates  a  database  file  with  the  fields  Field_name, 
Field_type,  Field_len  and  Field_dec.)  Then  it  ZAPs  the  contents 
of  Temp,  APPENDS  a  BLANK  record,  and  REPLACES  its  fields  with 
fields  that  will  hold  the  DIR  listing.  It  closes  Temp,  CREATES 
Dir_text  FROM  the  structure  defined  in  Temp,  and  opens  the  newly 
created  database  file. 

The  second  part  of  the  module  gets  the  name  of  the  memo  file  from 
m file.  After  initializing  mfilename  with  the  memo  file 
specification  (for  example  \ DBASE \ SAMPLES \ CUST .DBF) ,  the  module 
extracts  the  right  12  characters  of  mfilename.  The  IF...ENDIF 
then  removes  any  extraneous  characters  (here,  trimming 
LES \ CUST . DBF  to  CUST. DBF) .  Finally,  the  routine  changes  the  last 
character  to  a  T  (here,  producing  CUST. DBT) . 

The  last  part  of  the  UDF  RUNS  the  DOS  DIR  command  for  mfilename, 
redirecting  the  output  to  Dir.txt.  Then  it  APPENDS  the  contents 
of  Dir.txt  into  Dir  text,  the  file  created  earlier.  Each  record 
in  Dir_text  now  contains  one  line  of  the  DIR  listing.  The  routine 
LOCATES  the  record  containing  data  on  the  .dbt  file  and  extracts 
the  size  of  the  text  file.  It  uses  the  VAL()  function  to  convert 
the  string  to  a  numbei . 


-M- FUNCTION  Dbt  size-L- 
PARAMETERS  mTile-L- 
USE  Cust-L- 

COPY  TO  Temp  STRUCTURE  EXTENDED- L- 

USE  Temp-L- 

ZAP-L- 

APPEND  BLANK-L- 

REPLACE  Field  name  WITH  Dir_line,  Field_type  WITH  C,  ;-L~ 

Field  len  WITH  80-L- 
USE-L- 

CREATE  Dir  text  FROM  Temp-L- 
USE  Dir_text~L~ 

\m-L- 

mfilename  =  &mfile.-L- 
mfilename  =  RIGHT (mfilename , 12) -L- 
IF  "\"  $  mf ilename-L- 

mfilename  =  SUESTR (mfilename,  AT("\", mfilename)  +  1,  ;-L- 
LEN (mfilename)  -  AT("\", mfilename) )-L- 
ENDIF-L- 

mfilename  =  UPPER(LEFT(mfilename,  LEN(mfilename)  -  1)  +  "T")~I' 
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\m-L- 

RUN  DIR  ( &mf ilename . )  >  DIR.txt-L- 
APPEND  FROM  DIR.txt  TYPE  SDF-L- 
LOCATE  FOR  "DBT"  $  Dir  line-L- 
dbtsize  =  VAL ( SUBSTR (Dir  line, 13 , 9) ) ~L~ 
RETURN  dbt  size-N- 


~H4~Determining  available  disk  space 

Once  your  program  has  computed  the  total  size  of  a  database  file 
and  its  associated  memo  file  (see  previous  two  sections) ,  it  can 
determine  whether  there  is  sufficient  space  for  a  disk  operation. 
The  following  routine  prompts  users  when  there  is  not  enough 
space  on  disk  to  SORT  a  database  file: 

-M-DO  WHILE  .T.-L- 

IF  DISKSPACE ( )  <  (DBF  SIZE(mfile)  +  DBT  SIZE(mfile))  *  2-L- 
??  CHR(7)-L~ 
choice  =  "N"~L~ 

@  10,10  SAY  "Not  enough  room  on  disk  to  sort  this  file"~L~ 
@  11,10  SAY  "Delete  some  files  and  try  again?  (Y/N)  ";-L- 
GET  choice  PICTURE  "!"  VALID  choice  $  "YN"-L- 
READ-L- 

IF  choice  =  "Y"-L~ 

DO  Delefile-L- 
ELSE-L- 
EXIT-L- 
ENDIF-L- 
ELSE-L- 

SORT  ON  Amount  DESCENDING  TO  Temp-L- 
EXIT-L- 
ENDIF-L- 
ENDDO-N- 


You  can  also  use  the  UDFs  shown  above  to  determine  if  there  is 
enough  disk  space  for  a  file  backup  (see  "A  Backup  System") . 

-H2-BACKING  UP  DATA 

Backing  up  data  is  a  necessary  precaution  in  the  event  of 
catastrophic  data  loss,  such  as  a  power  failure  or  disk  crash. 
Don't  assume  that  users  of  your  applications  will  back  up 
database  files  in  DOS.  Your  applications  should  back  up  data 
automatically  or  provide  a  Backup  menu  option. 

This  section  explains  how  to  use  both  dBASE  and  external  commands 
in  record  and  file  backup  routines.  You  can  modify  the  routines 
shown  here  for  use  in  a  variety  of  applications. 

-H3-Saving  Data  to  Disk 

Whenever  your  program  APPENDS,  REPLACES,  or  otherwise  enters 
information  into  a  database  file,  that  information  is  written  to 
disk.  However,  to  maintain  maximum  performance,  dBASE  only 
updates  the  disk  file  and  directory  (the  DOS  file  access  table) 
periodically.  dBASE  does  a  more  complete  disk  update  when  your 
program  does  a  USE,  CLOSE  DATABASES,  or  QUIT. 
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If  you  want  dBASE  to  update  the  file  access  table  at  other  times, 
SET  AUTOSAVE  ON.  This  command  instructs  dBASE  IV  to  update  the 
disk  file  and  directory  after  a  record  update.  The  update 
operation  occurs  after  each  record  update  for  commands  that 
process  one  record  at  a  time,  such  as  APPEND,  BROWSE,  and  EDIT. 
For  commands  that  process  groups  of  records,  like  REPLACE,  SORT, 
and  TOTAL,  dBASE  IV  performs  the  disk  update  after  the  processing 
is  complete. 

SET  AUTOSAVE  ON  does  result  in  somewhat  slower  performance. 
Therefore,  your  program  should  SET  AUTOSAVE  ON  only  before  I/O 
intensive  operations,  such  as  REPLACE,  and  then  SET  AUTOSAVE  OFF 
when  the  operation  is  complete. 

-H3~Copying  Files 

dBASE  provides  commands  for  copying  both  open  and  closed  files. 

In  addition,  you  can  RUN  external  file  copy  commands,  such  as  DOS 
BACKUP  and  RESTORE,  from  within  a  dBASE  program. 

-H4-Copying  an  open  file 


dBASE  lets  you  COPY  data  from  an  open  database  file  to  a  closed 
one.  The  following  routine  uses  the  STRUCTURE  option  of  DEFINE 
POPUP  to  define  a  field  list  for  user  selection.  The  DO  WHILE 
loop  builds  a  list  of  the  fields  selected  by  the  user.  For  each 
selection,  it  adds  the  field  name  followed  by  a  comma  to  the 
list.  After  the  last  selection,  it  strips  the  final  comma  and 
aoes  a  COPY  FIELDS  using  the  defined  field  list. 

-M-filds  =  ""-L~ 

DEFINE  POPUP  fildspop  FROM  4,24  TO  17,62  PROMPT  STRUCTURE ; -L- 

MESSAGE  "Press  <Entei>  to  select  fields,  <Ctrl-Enter>  when  done” 
DO  WHILE  .T.-L- 

ACTIVATE  POPUP  fildspop-L- 
IF  ""  =  PROMPT  ()-L- 
EXIT-L- 
ENDIF-L- 

filds  =  filds  +  LEFT ( PROMPT ( ) ,  AT ( "  ",  PROMPT (p -1)  +  ","-L- 
§  18,0  SAY  "Fields  selected: "-L- 
§  19,0  SAY  filds-L- 
ENDDO-L- 

RELEASE  POPUP  fildspop-L- 

filds  =  LEFT (filds,  LEN( filds)  -  1)~L~ 

COPY  FIELDS  Sfilds.  TO  Newfile-N- 

-H4-Copying  a  closed  file 

You  can  back  up  closed  files  to  a  floppy  disk  using  the  DOS  COPY 
or  BACKUP  commands.  In  order  to  decide  which  command  to  use,  you 
need  to  determine  whether  the  files  will  fit  on  one  disk. 

To  figure  out  how  many  disks  are  required,  determine  the  size  of 
the  database  and  index  files  that  you're  backing  up.  (See 
"Determining  File  Size  and  Disk  Space"  earlier  in  this  chapter 
and  "Estimating  the  Index  File  Size"  in  Chapter  11.) 


May  17,  1988 


Page  6 


Programming  with  dBASE  IV 


Ch.  16,  Sec.  &  int. 

If  the  files  fit  on  a  single  floppy  disk,  use  DOS  COPY.  Remember 
to  copy  the  memo  (.dbt)  file,  if  any,  separately. 

-M- PROCEDURE  DOSCopy-L- 

?  "Insert  a  formatted  floppy  disk  in  drive  A:"-L- 
RUN  COPY  C:  *  .  dbf  A: -1,- 
RUN  COPY  C: * . dbt  A:-L~ 

?  "All  database  and  memo  files  have  been  copied"~L~ 

RETURN- N- 


If  the  files  to  be  copied  won't  fit  on  a  single  floppy  disk,  use 
DOS  BACKUP  and  RESTORE: 

-M-DEFINE  WINDOW  back_res  FROM  18,10  TO  22,65  COLOR  W/R,R/W,R-L- 

PROCEDURE  DOSback-L- 

ACTIVATE  WINDOW  back_res-L~ 

@  0,0  SAY  " - BACK  UP  DATA - "~L~ 

@1,0  SAY  "Insert  a  formatted  disk  in  drive  A:"~L~ 

WAIT  "Press  any  key  to  begin  backup"-L- 

RUN  BACKUP  C:  * . DBF  A:\-L- 

RUN  BACKUP  C:  * . DBT  A:\  /A-L- 

RUN  BACKUP  C:  *.MDX  A:\  /A-L- 

??  CHR(7)  -L- 

CLEAR-L- 

?  "******  BACKUP  PROCESS  FINISHED  ******"-L- 

WAIT-L- 

DEACTIVATE  WINDOW  back  res-L- 
RETURN-L- 
\m-L~ 

PROCEDURE  DOS_rest-L~ 

ACTIVATE  WINDOW  back_res-L- 

@0,0  SAY  " - RESTORE  DATA - "-L- 

@1,0  SAY  "Insert  first  backup  disk  in  drive  A:"~L~ 

WAIT  "  Press  any  key  to  begin  restoring"~L~ 

!  RESTORE  A:  * . DBF-L- 
!  RESTORE  A:  * . DBT-L- 
!  RESTORE  A:  *.MDX~L~ 

??  CHR(7) ~L~ 

CLEAR- L- 

?  "******  RESTORE  PROCESS  FINISHED  ******»-L- 

WAIT-L- 

DEACTIVATE  WINDOW  back_res-L- 
RETURN-N- 

-H3-A  Backup  System 

You  should  recommend  a  consistent  backup  routine  to  your  clients. 
Users  should  back  up  very  important  data  daily  to  another  disk 
(not  just  to  another  drive  of  the  same  disk) .  They  should  also 
make  weekly  archival  copies  of  all  database  files.  For  less 
important  data,  have  users  back  up  data  every  two  or  three  days, 
and  archive  the  data  every  two  weeks. 

Provide  a  menu  to  encourage  users  to  back  up  their  work.  Chapter 
8  explains  the  dBASE  IV  menu-building  commands  used  here.  The 
DOS  back  and  DOS_rest  procedures  were  shown  in  the  previous 
section. 
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-M-DO  BR  def-L- 

ON  SELECTION  POPUP  back_res  DO  BR_pop-L- 
SET  COLOR  TO  &c  popup. -L- 
ACTIVATE  POPUP  Eack_res-L- 
\m-L- 

PROCEDURE  BR_def-L- 

DEFINE  POPUP  back_res  FROM  3,10  TO  15,65  ;-L~ 

MESSAGE  "Press  <Enter>  to  select  option"-L- 
DEFINE  BAR  2  OF  back_res  PROMPT  "BACKUP  -  RESTORE  MENU"  SKIP-L- 


DEFINE  BAR  3  OF  back_res  PROMPT 
DEFINE  BAR  4  OF  back  res  PROMPT  "Back  up  data" 


;-L~ 


="-L- 


MESSAGE  "Backs  up  data  to  floppy  disks"-L- 
DEFINE  BAR  5  OF  back  res  PROMPT  "Restore  data"  ;-L- 
MESSAGE  "Restores  data  from  floppy  disks"-L- 
DEFINE  BAR  6  OF  back  res  PROMPT  "Exit"  MESSAGE  "Exit  to  main  me 
RETURN- L~ 

-L~ 


PROCEDURE  BR_pop~L~ 

DO  CASE-L- 

CASE  BAR()  =  6-L- 
EXIT-L- 

CASE  BAR()  =  4-L- 
DO  DOS  back-L- 
CASE  BAR(J  =  5-L- 
DO  DOS_rest-L- 
ENDCASE-L- 

SET  COLOR  TO  Sc_standard. -L~ 
RETURN-N- 


Assuming  your  program  contains  UDFs  like  DBF_SIZE  and  DBT_SIZE 
(see  "Determining  File  Size  and  Disk  Space"  above) ,  it  can  DO  a 
DOS  COPY  if  all  the  da<.a  fits  on  one  disk,  and  a  BACKUP  if  more 
than  one  disk  is  required: 

-M-IF  DISKSPACE ( )  >  DBF_SIZE (dbfsize)  +  DBT_SIZE (dbt_size) -L- 
DO  DOS_copy-L~ 

ELSE-L- 

DO  DOS_back-L- 
ENDIF-N- 

-H2 -MANAGING  DATA  TRANSACTIONS 

File  backups  let  you  re-create  data  from  earlier  versions,  and 
dBASE  IV  also  provides  the  capability  of  protecting  data  in  the 
course  of  a  transaction.  Transaction  management  is  a  system  for 
ensuring  the  integrity  of  data  during  operations  that  add  or 
change  records,  or  mark  them  for  deletion. 

dBASE  IV  provides  the  construct  BEGIN... END  TRANSACTION  for 
managing  data  transactions.  When  dBASE  encounters  BEGIN 
TRANSACTION,  it  creates  a  transaction  log  file  that  records 
changes  to  the  database  file.  (In  a  single-user  environment,  this 
file  is  called  Translog.log.)  In  the  event  of  a  catastrophe, 
dBASE  IV  can  use  this  file  to  restore  all  database  files  to  their 
state  when  the  BEGIN  TRANSACTION  command  was  issued. 
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dBASE  IV  also  puts  an  integrity  flag  in  the  database  file  header 
indicating  that  a  transaction  Is  in  progress  and  the  file  is  in 
an  inconsistent  state.  dBASE  IV  uses  this  flag  in  the  event  of  a 
transaction  failure  to  prevent  editing  of  an  inaccurate  file. 

See  Chapter  3  of  Networking  with  dBASE  IV  for  more  detailed 
information  about  transaction  management. 

-H2- PROTECTING  DATA 

While  hardware  failure  is  a  genuine  hazard  to  data,  human 
mishandling  of  data  can  be  equally  disastrous.  To  keep  such 
problems  to  a  minimum,  limit  the  accessibility  of  the  data  to 
those  individuals  who  need  to  work  with  it. 

dBASE  IV  provides  an  internal  utility  called  PROTECT  that  lets 
you  create  and  maintain  security  in  your  applications.  PROTECT 
makes  a  database  system  more  secure  by: 

-o-Preventing  unauthorized  users  from  logging  onto  the  system 

-o-Controlling  which  files  and  fields  each  user  may  access 

-o-Encrypting  the  data  in  database  f iles-ENDLIST- 

See  Chapter  2  of  Networking  with  dBASE  TV  for  more  detail  on 
PROTECT. 
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-Hl-TESTING  AND  DEBUGGING  YOUR  PROGRAM 

dBASE  IV  provides  a  full-screen  program  debugger  for  testing  and 
debugging  your  application.  This  final  stage  of  program 
development  is  essential  if  you  are  to  release  a  reliable 
finished  product. 

-H2-WHAT  THIS  CHAPTER  COVERS 

This  chapter  gives  you  some  tips  on  testing  your  application,  and 
describes  how  to  use  the  dBASE  IV  debugger.  The  topics  it  covers 
are: 

-o-Testing  your  application 

-o-Accessing  the  debugger 

-o-The  debugger  windows 

-o-The  debugger  commands 

-o-A  sample  debugging  session-ENDLIST- 

-H2-TESTING  YOUR  APPLICATION 


Your  application  should  be  thoroughly  tested  before  distribution. 
If  possible,  have  other  programmers  and  typical  users  test  it. 
Here  are  some  recommended  testing  techniques: 

-o-Before  beginning  to  test,  design  test  routines  (called  suites ) 
based  upon  what  the  program  specification  says  the  program  should 
be  able  to  do. 

-o-Use  the  test  suites  you've  designed  to  systematically  test 
each  version  of  the  software.  This  will  let  you  know  which  areas 
of  the  product  have  improved  and  which  have  regressed. 
(Improvements  in  one  part  of  a  program  can  often  wreak  havoc 
elsewhere. ) 

-o-Test  the  program's  boundaries.  For  example,  if  users  are  only 
allowed  to  enter  numbers  or  dates  within  a  certain  range,  enter 
data  outside  the  range  to  see  how  the  program  handles  the  data 
entry  error. 

-o-Try  to  "crash"  the  program.  Enter  nonsense,  type  very  quickly, 
rest  your  elbows  on  the  keyboard  —  do  whatever  you  can  to  break 
the  program.  A  well-designed  program  should  be  able  to  withstand 
such  abuse. -ENDLIST- 

Be  sure  to  keep  a  backup  copy  of  the  last  working  version  prior 
to  the  one  you're  testing.  You  might  have  to  go  back  to  that 
version. 
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-H2 -ACCESSING  THE  DEBUGGER 

dBASE  IV  provides  a  program  debugger  to  assist  you  in  correcting 
program  errors.  You  can  activate  the  debugger  in  three  ways: 

-o-With  SET  TRAP  ON,  the  debugger  opens  automatically  when  a 
program  error  is  encountered 

-o-With  SET  TRAP  ON,  the  debugger  opens  if  you  press  -ESC-  while 
a  program  is  running 

-o-You  can  open  the  debugger  directly  by  entering  DEBUG 
<.prg  tilename>  at  the  dot  prompt-ENDLIST- 

-H2-THE  DEBUGGER  WINDOWS 

The  debugger  screen  is  divided  into  four  windows  (see  Figure 
17-1) : 


-SCREEN-Figure  17-l\mSample  debugger  screen-ENDFIG- 


These  windows  do  not  overlap  like  other  dBASE  IV  windows.  Rather, 
they  lie  side-by-side  like  tiles,  and  their  size  and  position  are 
fixed.  You  can  modify  the  default  single-line  border  with  the  SET 
BORDER  command. 

The  usual  dBASE  IV  editing  and  navigation  keys  operate  in  all 
debugger  windows  except  in  the  right  side  of  the  display  window 
(see  "The  Display  Window") .  Press  -F9-  to  toggle  the  debugger 
screen  on  and  off.  As  always,  be  sure  to  save  your  program 
changes  with  -CONTROL - END-. 

-H3-The  Debug  Window 

The  debug  window  is  active  when  you  first  activate  the  debugger. 
After  activating  another  window,  press  -ESC-  to  get  back  to  the 
debug  window. 

This  window  shows  general  database  file  and  program  information 
(see  Figure  17-1  above)  .  Note  that  the  line  number  is  relative  tc 
the  beginning  of  the  program  or  procedure  file,  not  to  the 
beginning  of  the  procedure. 

You  issue  debugger  commands  at  the  ACTION:  prompt  in  the  debug 
window  (see  "The  Debugger  Commands") . 

-H3-The  Edit  Window 

To  access  the  edit  window,  type  -E-  at  the  ACTION:  prompt.  This 
window  displays  the  actual  program  commands  as  they  execute.  The  j 
next  line  to  be  executed  appears  in  inverse  video. 
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Use  the  edit  window  just  as  you  do  the  program  editor.  Changes 

that  you  save  (with  -CONTROL - END-)  are  added  to  the  source 

code,  but  they  do  not  execute  until  you  recompile  the  program. 

~H3~The  Breakpoint  Window 

Type  -B-  at  the  ACTION :  prompt  to  activate  the  breakpoint 
window.  Breakpoints  are  dBASE  conditions  for  which  the  debugger 
halts  program  execution.  Type  each  breakpoint  on  a  separate  line 
in  the  breakpoint  window.  You  can  enter  up  to  ten  breakpoints; 
the  debugger  assigns  a  line  number  to  each  (see  Figure  17-1 
above) .  You  may  enter  conditions  that  use  variables  you  haven't 
yet  defined.  Just  ignore  the  error  message  and  define  the 
variable  later. 

The  debugger  evaluates  the  breakpoints  after  each  line  of  code  is 
processed.  If  a  condition  evaluates  to  true,  the  debugger  stops 
the  program  and  activates  the  debug  window.  In  addition,  the 
message  Breakpoint  appears  on  the  message  line,  followed  by  the 
line  number  of  the  breakpoint  that  caused  the  halt. 

-H3-The  Display  Window 

To  activate  the  display  window,  type  -D-  at  the  ACTION:  prompt. 
This  window  shows  the  status  of  the  program  environment.  You 
enter  one  or  more  expressions  on  the  left  side  of  the  display 
window.  The  debugger  evaluates  the  expressions  after  each  line  of 
code  is  processed,  and  displays  their  results  in  the  right  side 
of  the  window. 

Unlike  the  other  windows  in  the  debugger,  the  right  side  of  the 
display  window  is  read-only.  It  scrolls  vertically  in  conjunction 
with  the  left  side. 

Figure  17-1  above  shows  a  sample  display  window.  Note  that  you 
need  only  enter  the  expression  you  want  evaluated,  not  the  ? 
command  verb.  Be  sure  that  your  entry  is  a  valid  dBASE 
expression. 

-H2-THE  DEBUGGER  COMMANDS 

You  control  the  debugger  with  a  few  simple  commands  and  keys  (see 
Table  17-1) .  Type  the  commands  at  the  ACTION:  prompt  without 
pressing  -RETURN-.  The  first  three  commands  listed  in  the  table 
access  the  various  debugger  windows  (see  "The  Debugger  Windows" 
above) .  More  detailed  descriptions  of  the  other  commands  follow. 

-TABLE-Table  17-l\mDebugger  commands  and  keys 

Command  Action 

B  Enters  the  breakpoint  window 

D  Enters  the  display  window 
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E  Enters  the  edit  window 

R  Runs  program  until  breakpoint  or  error  occurs 

L  Begins  execution  at  specified  line 

[<n>]S  Steps  through  program  <n>  steps  at  a  time 

[<n>]N  Steps  through  program  <n>  steps  at  a  time  at 

current  or  higher  level  only 
P  Shows  trace  of  calling  programs/procedures 

X  Suspends  program  and  exits  to  dot  prompt 

Q  Quits  the  debugger  and  cancels  program 


Key1 


Action 


-RETURN- 

-ESC- 

-Fl- 

-F9- 


Issues  a  IS  or  IN,  whichever  is  most  recent 
Opens  the  debug  window 

Displays  Help  menu  of  debugger  commands 
Toggles  debugger  windows  on  and  off 


1.  Only  designated  debugger  keys  are  shown.  Other  keys  behave  as 
they  do  in  the  program  editor. -ENDTABLE- 

-H3 -Running  a  Program 

To  run  a  program  from  within  the  debugger,  type  -R-  at  the 
ACTION:  prompt.  The  program  executes  until  a  breakpoint  or 
program  error  occurs. 

Use  the  L  command  to  begin  execution  at  a  particular  line.  When 
you  type  -L~  at  the  ACTION:  prompt,  the  debugger  prompts  you  to 
enter  a  line  number.  Enter  the  desired  line  number,  or  press 
-RETURN-  to  begin  at  the  current  line. 

-H3-Stepping  Through  a  Program 

In  order  to  find  a  particularly  elusive  bug,  you  can  trace 
through  your  program  one  or  more  steps  at  a  time.  Enter  -S-  or 
-RETURN-  repeatedly  at  the  ACTION:  prompt  to  step  through  a 
program  one  line  at  a  time.  (The  trace  skips  comment  lines.) 

To  speed  up  the  trace,  precede  the  S  command  with  a  number.  For 
example,  10S  stops  the  trace  at  every  10  commands.  To  limit  the 
trace  to  the  current  program  level  or  higher,  use  the  N  command 
rather  than  S.  Procedures  at  a  level  deeper  than  the  current  one 
will  execute,  but  they  will  not  count  as  separate  commands  in  the 
trace. 

When  tracing  through  a  program,  the  debugger  stops  at  breakpoints 
and  errors  as  well  as  the  specified  trace  points.  After  all 
commands  have  executed,  control  returns  to  the  debug  window. 
(Press  -ESC-  to  stop  the  trace  prematurely.) 

-H3~Displaying  Parameters  in  a  Window 
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If  you  want  to  see  a  list  of  all  calling  programs  and  procedures, 
with  the  values  of  any  parameters  passed  to  them,  type  ~p~  at 
the  ACTION:  prompt.  The  list  appears  in  a  special  window  that 
opens  near  the  bottom  of  the  screen.  Figure  17-2  shows  a  sample 
parameters  window. 

-SCREEN-Figure  17-2\mSample  parameters  window-ENDFIG- 


-H3 -Suspending,  Resuming,  and  Quitting  the  Debugger 

To  suspend  the  debugger  and  exit  to  the  dot  prompt,  type  -X-  at 
the  ACTION:  prompt.  Once  at  the  dot  prompt,  you  enter  commands  in 
the  usual  manner.  Enter  RESUME  at  the  dot  prompt  to  re-enter  the 
debugger. 

If  you  want  to  cancel  rather  than  suspend  the  program  before 
going  to  the  dot  prompt,  type  -Q-  at  the  ACTION:  prompt.  This 
cancels  both  the  debugger  and  the  program  and  returns  control  to 
the  dot  prompt. 

-H2-A  SAMPLE  DEBUGGING  SESSION 


-M-*  Program:  Filldate-L- 

*  - Declares  and  fills  an  array  with  the  next  five  dates-L- 

DECLARE  dates [5] -L- 

offset  =  0-L- 

*  - Fill  the  array  with  the  next  five  dates-L- 

DO  WHILE  offset  <=  6-L- 

dates[offset]  =  DATE()  +  offset-L- 
offset  =  offset  +  1-L- 
ENDDO-L- 
RETURN-L- 

*  EOP:  Filldate-N- 

At  first  glance,  the  Filldate  procedure  looks  sound.  When  this 
-outi.  e  is  compiled,  no  errors  are  produced.  However,  command 
i  r.  -  4  and  6  will  produce  errors  at  run  time. 

Line  4  incorrectly  initializes  a  pointer  (offset)  for  the  array 
dates.  When  the  routine  executes,  the  error  message  Bad  array 
dimension(s)  occurs  the  first  time  line  7  executes  because  the 
lowest  allowed  value  for  an  array  pointer  is  one,  not  zero. 

The  DO  WHILE  condition  in  line  6  instructs  the  program  to 
continue  looping  until  offset  is  less  than  or  equal  to  six. 
However,  line  3  assigns  a  maximum  of  five  elements  to  the  array. 
On  the  sixth  pass  through  the  loop,  the  same  error  message  is 
produced  because  the  value  of  offset  is  one  greater  than  the  size 
of  the  array. 
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To  start  debugging,  issue  the  following  commands: 

-M-.  -I-SET  TRAP  ON-L- 
.  DO  Filldate-N- 

-NOTE- Alternately,  you  can  enter  DEBUG  Filldate  at  the  dot  prompt 
to  invoke  the  debugger  and  then  press  -R-  at  the  ACTION:  prompt 
to  execute  the  code . -ENDNOTE- 

The  debugger  is  activated  when  the  first  error  on  line  7  occurs. 

At  the  ACTION:  prompt,  press  -D-  to  go  to  the  display  window.  On 
the  first  two  lines,  enter  the  expressions  offset  and 
dates [of f set] .  The  display  window  reveals  that  offset  has  a  value 
of  zero  but  dates [of f set]  has  bad  array  dimensions. 

Realizing  that  the  mistake  was  in  line  4  and  not  line  7,  you  can 
correct  the  mistake  by  modifying  the  program  file.  Press  -ESC-  tc 
return  to  the  debugger  window  and  press  -E-  to  edit  the  program 
file.  Change  line  4  to: 

-M-offset  =  1-N- 

and  save  the  changes  with  -CTRL - END-.  Since  the  source  code  was 

updated,  the  display  in  the  edit  window  reflects  the  change. 
However,  the  object  code  is  not  updated  yet.  You  will  have  to 
recompile  your  program  before  running  that  line  again. 

Though  the  erroneous  command  in  line  4  was  corrected,  the  value 
of  offset  has  not  changed.  Press  -X-  to  temporarily  exit  the 
debugger  and  return  to  the  dot  prompt.  At  the  dot  prompt,  change 
the  value  of  offset  and  then  return  to  the  debugger: 

-M-.  -I-of f set  =  1-L- 
.  RESUME-N- 

Notice  that  the  values  in  the  display  window  have  changed.  The 
value  of  offset  is  now  1  and  the  value  of  dates [of f set]  is  false. 
Press  -R-  to  resume  execution  of  the  program.  dBASE  IV  executes 
the  program  until  the  second  error  occurs. 

The  display  window  reveals  that  offset  now  has  a  value  of  6,  too 
large  to  be  used  for  the  array  dates.  Correct  the  DO  WHILE 
condition  in  the  editor  by  changing  the  command  to: 

-M-DO  WHILE  offset  <=  5-L- 

The  edit  window  now  shows  the  correct  code,  but  the  current  line  | 
is  still  within  the  loop  on  line  7.  Since  you  do  not  want  to 
reproduce  the  error  message,  skip  to  the  first  line  after  the 
ENDDO  by  instructing  the  debugger  to  advance  three  lines.  First  | 
press  -L-  to  indicate  that  you  want  to  resume  execution  on  a  new 
line.  The  debugger  prompts  you  for  the  line  number  to  begin  on. 
Enter  -10- . 
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The  program  now  continues  to  execute  and  returns  control  to  the 
dot  prompt.  If  you  do  not  wish  to  invoke  the  debugger  again  this 
session,  SET  TRAP  OFF. 
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About  RunTime 


Once  you’ve  mastered  dBASE  IV  programming,  you  might  want  to  distribute 
stand-alone  application  programs.  This  manual  helps  you  develop  stand¬ 
alone  programs  for  use  with  the  RunTime  interpreter. 

This  manual  will: 

■  Describe  and  tell  you  how  to  use  RunTime,  including  several  tips 

■  Describe  in  detail  how  to  run  the  BUILD  and  DBLINK  utilities 

RunTime  is  capable  of  interpreting  object  programs  from  the  dBASE  IV 
compiler.  Single  or  unlimited  multi-user  capability  is  provided  by  the  same 
RunTime  interpreter. 


stays  in  the  drive,  and  disk  3  contains  infrequently  used  routines.  For 
example,  a  basic  text  editor  is  provided  on  disk  3. 


NOTE 

RunTime  will  run  on  a  dual  floppy  system.  The  programs  on  the  three 
original  RunTime  disks  are  erouped  so  that  disk  1  is  removable,  disk  2 


What  Is  a  RunTime  Application? 

RunTime  is  a  program  that  executes  your  compiled  code,  enabling  you  to 
distribute  stand-alone  applications  developed  in  dBASE  IV.  There  are  two 
utility  programs,  BUILD  and  DBLINK,  provided  to  help  you  create  an  appli¬ 
cation  you  can  distribute.  BUILD  automatically  uses  the  dBASE  IV  COMPILE 
command  on  your  program  (-prg,  .prs,  .fmt)  files.  As  a  side  benefit,  the  com¬ 
piled  code  ensures  that  others  cannot  tamper  with  your  program.  BUILD  can 
invoke  DBLINK  if  you  wish  to  link  all  the  dependent  object  Hies  into  one 
executable  file. 

If  you  decide  not  to  use  DBLINK,  you  must  make  sure  all  the  files  called  by 
your  application  are  on  the  disk.  Some  developers  prefer  having  multiple 
unlinked  files  so  they  only  have  to  change  and  distribute  the  modified  mod¬ 
ule.  By  using  DBLINK,  you  end  up  with  far  fewer  files  on  your  distribution 
disk.  However,  every  time  you  make  a  change  to  your  application,  you  must 
link  all  your  files  again. 

Ybu  can  run  the  compiled  or  linked  files  with  dBASE  IV  or  any  compatible 
future  version.  You  cannot  use  an  earlier  version  of  dBASE. 
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If  your  customers  do  not  own  dBASE  IV,  you  can  deliver  your  program  with 
a  special  version  of  dBASE  IV  called  RunTime.  RunTime  is  functionally 
equivalent  to  dBASE  IV;  however,  it  can  only  run  files  compiled  by 
dBASE  IV  or  linked  with  DBLINK. 


Requirements  For  Creating  A  RunTime  Application 

RunTime  Utilities 

The  BUILD  utility  is  made  up  of  the  following  four  files.  All  of  the  files  must 
be  in  the  same  subdirectory. 

■  Build.exe  —  This  is  the  only  file  you  need  to  call. 

■  Build. res  —  Called  by  Build.exe 

■  Buildx.exe  —  Called  by  Build.exe 

■  Buildx.res  —  Called  by  Buildx.exe 

The  DBLINK  utility  is  made  up  of  two  files.  Both  files  must  be  in  the  same 
sub-directory. 

■  Dblink.exe  —  Called  by  Build.exe 

■  Dblink.res  —  Called  by  Dblink.exe 


RunTime 

The  RunTime  files  that  must  be  made  available  for  each  application  are: 

■  Runtime.exe 

■  Runtimel.ovl 

■  Runtime2.ovl 

■  Runtime3.ovl 

■  Runtime4.ovl 

■  dBASEl.res 

■  Protect. ovl 


Support  for  the  PROTECT  command  is  in  the  Protect. ovl  file.  If  you  do  not 
want  your  user  to  change  field  access  levels,  do  not  copy  Protect.ovl  to  your 
distribution  disk.  Also,  do  not  include  the  command  PROTECT  in  the  source 
code.  RunTime  supports  encrypted  data  regardless  of  whether  Protect.ovl  is 
provided. 
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Are  You  Ready  For  RunTime? 

Before  using  RunTime,  you  should  be  an  experienced  dBASE  IV  program¬ 
mer.  You  should  also  understand  the  basics  of  DOS  file  management,  espe¬ 
cially  how  to  work  with  directories.  Your  program  should  already  be  written, 
tested,  and  debugged.  You  should  only  work  with  RunTime  when  you  have  a 
finished  program,  one  that  has  been  thoroughly  tested  and  that  you  feel  is 
ready  for  the  real  world. 

Remember  that  this  is  your  program  and  you  must  stand  behind  it 
completely.  You  are  responsible  for  its  documentation  and  technical  support. 


NOTE 

Ashton-Thte  will  not  offer  assistance  to  users  of  your  application  pro¬ 
grams.  You  must  provide  this  yourself.  Ashton-Thte's  Software  Support 
center  will  direct  all  calls  regarding  your  program  to  you. 


RunTime  Restrictions 

RunTime  will  not  support  the  following  dBASE  IV  commands: 

■  Ampersand  substitution  of  command  verbs 

■  ASSIST 

■  COMPILE 

■  CREATE/MODIFY  FILE 

■  CREATE/MODIFY  LABEL 

■  CREATE/MODIFY  REPORT 

■  CREATE/MODIFY  QUERY 

■  CREATE/MODIFY  SCREEN 

■  CREATE/MODIFY  STRUCTURE  (full-screen) 

■  CREATE/MODIFY  VIEW  (full-screen) 

■  HELP 

■  HISTORY 

■  Menu-driven  SET 

■  SET  DEBUG 

■  SET  DOHISTORY 

■  SET  ECHO 

■  SET  HISTORY 

■  SET  INSTRUCT 

■  SET  SQL 
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■  SET  STEP 

■  SET  TRAP 

■  SUSPEND 


How  to  Use  RunTime 

To  prepare  stand-alone  applications,  use  the  BUILD  utility  outside  of 
dBASE  IV.  You  must  make  sure  that  all  the  program  files  for  your  applica¬ 
tion,  whether  prg  or  .prs,  are  in  the  current  directory.  At  the  system  prompt, 
type  BUILD.  Then,  at  the  Compile  {filename} prom pt,  enter  the  filename  of 
the  main  module  of  your  application.  See  Chapter  3,  “Using  BUILD,”  for  a 
complete  discussion  of  the  options  available  to  you. 

NOTE 

RunTime  provides  for  an  unlimited  number  of  users  and  no  special 
installation  is  required.  It  is  your  responsibility  to  code  your  applica¬ 
tions  for  multi-user  access. 

RunTime  is  invoked  by  having  the  user  type  RUNTIME  <  filename >  at  the 
system  prompt.  RunTime  will  try  to  find  and  execute  a  dbo  file  of  this  name. 
If  the  specified  file  is  not  found,  RunTime  will  return  to  the  system  prompt. 

Alternatively,  you  may  type  RUNTIME  without  specifying  a  filename.  The 
disk  is  then  searched  for  the  default  filename  Dbruncmd.dbo. 

Documentation  and  Technical  Support  for  Your  Program 

You  are  responsible  for  your  programs.  Make  sure  that  you  distribute  all  the 
necessary  information  to  run  your  application.  Ashton-Thte  cannot  provide 
support  for  your  distributed  applications. 


1-4 


ABOUT  RUNTIME 


PAGE:  1  SESS:  4  Fri  May  6  16: AS: A8  1988 
I  iK2/b  I  I  J  obz/CLS_»nBnhBt  /GRP_jn*nh«t/ JOB _jn«nrunt/DI  V_r  tch»p2 

DBLINK 


DBLINK  is  a  stand-alone  utility  that  links  several  dBASE  IV  object  files  into 
one  single  object  file.  You  would  use  BUILD  if  you  needed  your  output  to  be 
divided  into  several  RunTime  object  files. 

This  means: 

■  Easier  development,  as  the  entire  application  does  not  have  to  be  recom¬ 
piled  if  only  one  or  two  program  modules  are  changed. 

■  Faster  execution  of  the  final  application,  as  there  is  only  one  file  that  has 
to  be  accessed  by  the  RunTime  engine. 

■  Less  disk  space  for  the  final  application,  as  there  is  only  a  single  object 
file. 


Using  DBLINK 

To  use  DBLINK,  type  DBLINK  <  input  filename >  /L  and  press  «-*. 


ACfi 

MAY  fi  p.n 


NOTE 

Make  sure  you  have  the  files  Dblink.exe  and  Dblink.res  in  the 
directory. 


<  input  filename  >  is  the  name  of  the  main  module  of  your  application. 
DBLINK  goes  through  this  file  identifying  all  the  command  and  procedure 
files  that  it  calls.  It  then  goes  through  each  of  these  called  files  looking  for 
additional  called  command  and  procedure  files.  DBLINK  will  repeat  this 
procedure  until  all  called  command  and  procedure  files  are  identified.  The 
main  module  and  all  command  and  procedure  files  that  have  been  found  are 
then  linked  into  one  object  file. 


M  WARNING 

Only  explicit  external  file  references  are  found  by  DBLINK  and 
BUILD.  Macros  that  contain  filenames,  like  DO  Amemvar,  are  not 
expanded.  Consequently,  these  files  will  not  be  referenced  by  the 
utilities. 
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The  resulting  object  file  has  the  same  name  as  the  main  module,  but  with  a 
.dbo  extension.  The  original  is  renamed  with  a  .bale  extension. 

All  input  files,  including  the  main  module,  must  be  compiled  with  dBASE  IVs 
COMPILE  or  DO  commands  before  being  linked.  If  an  input  file  is  not  found 
or  is  not  an  object  file,  it  will  not  be  linked.  The  original 
DO  <  filename  >  command  will  still  be  in  the  linked  calling  file.  This  can 
slow  the  program  execution  time. 

Because  DBLINK  combines  object  files,  you  can  include  compiled  format 
and  .prs  (SQL  program)  files  within  your  finished  application. 

NOTE 

You  cannot  combine  format  and  prs  files  into  one  large  prg  file 
at  the  source  code  level.  They  must  first  be  compiled  and  then  linked. 
DBLINK  allows  you  to  combine  mixed  file  types,  compiled  by 
dBASE  IV,  into  dbo  files. 

The  maximum  size  and  number  ofprocedures  supported  by  DBLINK  are  the 
same  as  for  .dbo  files  throughout  pBASE  IV.  This  means  you  may  have  up  to 
65,520  bytes  of  compiled  code  per  procedure,  with  a  maximum  of  1,170  pro¬ 
cedures  per  .dbo  file.  The  actual  number  ofprocedures  that  can  be  accessed 
depend^on  the  free  RAM  available  in  the  operating  environment. 


The  / L  Option 

This  option  creates  a  document  listing  the  files  that  were  linked  and  the  pro¬ 
grams  that  are  referenced  but  not  linked.  This  information  is  placed  in  a  text 
file  with  the  same  name  as  the  main  source  file,  but  with  a  .txt  extension. 

Messages 

If  a  referenced  file  cannot  be  located  by  DBLINK,  the  message  Cannot  open 
<  input  filename  >  File  <  input  filename  >  does  not  exist  appears. 


Upon  the  completion  of  the  linking  process  the  message  Press  RETURN  to 
proceed  appears.  This  will  take  you  back  to  either  the  DOS  prompt  or 
BUILD. 
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Using  BUILD 


BUILD  is  the  stand-alone  utility  that  automatically  compiles  and  optionally 
links  your  programs  for  use  by  dBASE  IV  or  RunTime. 


NOTE 

You  must  run  BUILD  from  the  DOS  prompt  as  it  invokes  dBASE  IV. 
If you  try  to  run  BUILD  from  the  dot  prompt,  the  DOS  Insufficient 
Memory  error  message  appears. 


BUILD  has  three  basic  functions: 

■  Parsing  all  program  files  regardless  of  extension.  This  means  .prg,  prs, 
.rpt,  and  .lbl  files,  and  any  other  file  that  is  executed  by  your  main  pro¬ 
gram.  BUILD  will  use  dBASE  IV  to  compile  the  main  calling  file,  all 
dependent  files,  and  user-defined  functions. 

■  Optionally,  invoking  the  DBLINK  utility  to  link  together  all  dependent 
object  files  into  one  RunTime  file. 

■  Copying,  at  your  option,  all  the  RunTime  application  files  (including 
such  things  as  data  files,  views,  and  indexes,  as  well  as  the  RunTime 
interpreter)  to  a  target  directory  or  series  of  disks. 


Getting  Ready 

Before  you  run  BUILD  you  should  do  the  following: 

■  Make  sure  that  all  the  BUILD  utility  files  are  in  the  dBASE  IV  directory 
and  that  this  directory  name  appears  in  the  DOS  path.  The  necessary  files 
are: 

■  Build.exe 

■  Buildx.exe 

■  Build.res 

■  Buildx.res 

■  Copy  all  necessary  application  files  to  the  current  directory.  This  does 
not  have  to  be  the  dBASE  IV  directory. 

■  If  DBLINK  is  to  be  used,  make  sure  that  it  is  in  the  dBASE  IV  directory. 
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■  If  the  output  files  are  to  be  copied  into  a  directory,  make  sure  that  direc¬ 
tory  exists.  If  the  output  files  are  being  sent  directly  to  floppy  disks, 
make  sure  that  they  are  formatted. 

■  If  the  application  exceeds  the  maximum  number  of  command  files 
allowed  by  DBLINK,  or  the  application  is  too  large  to  fit  on  a  floppy 
disk,  create  the  text  file  Build. mod.  This  file  is  discussed  in  detail  in  the 
“Using  Build. mod”  section  in  this  chapter.  Note  the  maximums  below: 

■  There  is  a  maximum  of  65,520  bytes  of  compiled  code  per  procedure. 

■  There  is  a  maximum  of  65,520  bytes  of  compiled  code  within  a  rela¬ 
tive  branch  such  as  a  DO  WHILE  loop. 

■  There  is  a  maximum  of  32  active  .dbo  files  allowed.  A  file  is  active  if 
it  can  be  accessed  by  a  RETURN  or  if  it  is  the  file  named  in  a  SET 
PROGRAM  or  SET  SQLPROGRAM  command. 

The  modular  outputs  will  each  have  the  filename  of  the  senior  command  file 
as  listed  in  Build. mod 


Running  BUILD 

At  the  DOS  prompt,  type  C:BUILD  and  press  •*-►. 
The  screen  shown  in  Figure  2-1  appears. 


Figure  2-1  The  BULD  screen 

You  any  choose  either  of  the  two  menus  or  exit  at  this  point. 
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The  BUILD  Menu 


Figure  2-2  The  BULD  menu 

The  Compile  filename} option  accepts  the  filename  of  the  main  module  of 
your  application.  You  do  not  have  to  include  the  .prg  or  .prs  extension.  After 
pressing  ♦♦,  press  Shift-FI  to  obtain  a  list  of  files  in  the  current  directory. 
BUILD  assumes  that  the  files  to  be  parsed  and  compiled  are  in  the  current 
directory. 

The  Link  ye  s/no  option  tells  BUILD  whether  or  not  to  invoke  the  LINK  util¬ 
ity  following  the  compiling  of  your  application  files.  The  default  is  yes. 

The  Outpnt  destination  submenu  determines  the  destination  of  the  finished 
application  with  all  its  associated  files.  The  submenu  options  are  Drive  {} 
and  Path  {}  If  they  are  left  blank,  your  compiled  and  linked  application  files 
will  be  put  in  the  current  directory  only.  If  these  options  are  filled  in,  the 
output  of  the  BUILD  utility  will  be  placed  in  the  target  directory. 

You  may  also  specify  the  floppy  disk  drive  if  you  wish  your  application  to 
output  directly  to  floppy  disks.  Or  you  may  specify  another  subdirectory  in 
order  to  consolidate  all  your  application  files.  This  is  useful  if  your  source 
files  are  in  different  subdirectories. 


The  final  option  is  Perform  BUILD,  which  starts  the  BUILD  program. 


NOTE 

DBUNK  will  rename  your  original  file  with  a  .bac  extension. 


II 
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Options  Menu 


Figure  2-3  The  Options  menu 

The  Search  for  new  functions  yes/no  option  instructs  BUILD  to  search  for 
potential  user-defined  functions  (UDFs)  that  may  be  identical  to  dBASE  IV 
functions.  Applications  that  have  been  developed  outside  of  dBASE  IV  may 
have  existing  UDFs  that  duplicate  current  dBASE  IV  keywords  (for  example, 
SIN()).  These  UDFs  are  considered  redundant  and  will  not  be  executed; 
instead,  the  new  dBASE  IV  functions  will  be  used.  Alist  of  your  functions 
that  duplicate  the  new  dBASE  IV  functions  will  appear. 

The  default  is  no.  If  you  answer  yes  to  this  option,  BUILD  will: 

■  Identify  all  functions  tha:  duplicate  a  dBASE  IV  keyword. 

■  Provide  you  with  the  message  UDF  <  filename >  may  be  redundant.  If 
you  have  a  UDF  by  this  name,  it  will  not  be  compiled,  and  therefore 
never  executed.  BUILD  will  provide  a  list  of  suspect  UDFs  that  you  must 
check. 

The  Accept  only  RunTime  commands  determines  whether  dBASE  IV  issues 
an  error  message  if  an  illegal  RunTime  command  is  parsed.  The  default  is 

yes. 

The  Include  file  types  option  displays  a  list  of  all  the  dBASE  IV  file  types 
followed  by  yes/no.  Use  this  option  to  determine  which  file  types  are 
included  in  the  final  copy  operation  that  builds  the  RunTime  application  set. 
The  default  is  yes.  This  option  has  no  effect  on  the  compile  and  link  process; 
it  only  affects  the  copy  process.  This  is  useful  when  recompiling  because 
only  those  files  that  have  been  changed  need  to  be  copied  over. 
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The  Print  messages  to ...{}  option  is  an  enumerated  field  directing  the  mes¬ 
sage  output  of  BUILD.  The  File  option  sends  messages  to  a  file  named 
Build.txt.  Printer  and  File  both  echo  messages  to  the  screen.  Screen  is  the 
default. 


The  Copy  single-user  RunTime  yes/no  option  directs  BUILD  to  copy  an 
.installed  version  of  single-user  RunTime  to  the  finished  application  during 
RunTime. 


NOTE 

If  you  choose  no  ,  you  will  not  automatically  get  multi-user  RunTime. 
Single-user  RunTime  can  simply  be  copied  to  your  application  disk. 
Multi-user  RunTime  must  be  installed  for  every  application.  See  the 
section  on  multi-user  in  this  manual  for  more  information  about  this 
option. 

>cate  RunTime  source  directory  option  displays  a  submenu  through 
you  can  fill  in  the  drive  and  path  containing  the  installed  single-user 
me.  The  default  is  set  to  the  installation  defaults  in  DBSETUP. 


Using  Build.mod 

Build. mod  is  a  text  file  containing  the  filenames  of  command  files  that  begin 
application  sub-modules.  You  only  have  to  specify  the  filename  and  do  not 
have  to  include  the  file  extension.  The  name  of  the  application’s  main  mod¬ 
ule  must  still  be  entered  in  the  Compile  option  of  the  Build  submenu.  If 
Build.mod  is  not  found  in  the  current  directory,  BUILD  will  not  segment  the 
application. 

BUILD  parses  the  main  application  module  and  builds  a  file  of  external  com¬ 
mand  file  references.  It  checks  for  files  listed  in  Build.mod  but  not 
referenced  in  the  application.  If  such  files  are  found,  the  message  Warning: 
Module  <  filename >  not  referenced  in  application  will  appear  and 
BUILD  will  continue. 

Every  object  file  corresponding  to  a  file  in  Build.mod  receives  a  temporary 
file  extension,  .xxx,  which  DBLINK  cannot  recognize.  The  DBLINK  utility  is 
then  called  and  links  together  all  object  files  it  can  recognize. 

BUILD  goes  through  the  list  of  files  in  Build.mod  and  changes  the 
corresponding  object  file  to  the  recognizable  extension  (  dbo).  This  file  and 
its  subsidiary  files  are  then  processed  by  DBLINK  and  control  is  returned  to 
BUILD  so  that  the  next  file  in  Build.mod  can  be  processed. 
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Application  Modules  Created  by  Build.mod 

The  compiled  and  linked  application  modules  have  the  filename  of  the  com¬ 
mand  file  listed  in  Build.mod.  They  will  have  the  normal  .dbo  extension. 


Figure  3-1  Programs  in  a  typical  application 

If  you  create  a  Build.mod  file  that  contains  three  program  names  from  the 
application,  Build.mod  will  create  four  linked  and  compiled  modules:  the 
three  programs  and  all  their  subsidiary  programs,  plus  the  main  program 
and  its  subsidiary  programs  which  have  not  already  been  incorporated. 


Suppose  Build.mod  contains  the  filenames  Menul,  Module4,  and  Procfile, 
and  Mainmenu  was  the  filename  specified  at  the  compile  option.  The  four 
modules  described  below  would  be  created: 

■  Mainmenu. dbo 

This  is  made  up  of  the  files: 

Mainmenu. prg  Menu2.prg  Module3.prg  Program07.prg  Program08.prs 
Program09.prg 

■  Menul. dbo 

This  is  made  up  of  the  files: 

Menul.prg  Modulel.prg  ProgramOl.prg  Program02.prs  Program03.prg 
Module2.prs  Program 04. prg  Program05.prs  Program06.prg 

■  Module4.dbo 

This  is  made  up  of  the  files: 

Mo4«le4.prg  Program  lO.prs  Program  ll.prs  Program  12.prs 
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■  Procflle.dbo 

This  is  made  up  of  the  files: 

Procfile.prg  Procl.prg  Proc2.prg  Proc3.prg  Proc4.prg 


BUILD  Output 


BUILD  will  output  a  compiled  and  linked  application  ready  to  be  given  to 

your  users.  It  can  include: 

■  dbo  files  for  all  .prg  and  .prs  files  used  in  the  application  in  the  same 
directory  as  the  source  files. 

■  If  LINK  was  invoked,  the  .dbo  file  with  the  same  prefix  as  the  application 
main  module  will  include  the  linked  files. 

■  The  application  files  on  disk  and,  if  requested,  the  single-user  RunTime 
and  batch  file  for  installation. 

■  Output  messages  to  the  screen,  printer,  or  file. 

Unless  an  alternate  path  is  specified,  BUILD  will  write  all  output  files  to  the 

current  drive  and  directory. 
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-Hl-WHAT'S  NEXT? 

Even  though  you've  designed,  written,  tested,  and  debugged  your 
application,  it  is  still  not  quite  ready  for  distribution.  This 
chapter  looks  at  what  remains  to  be  done. 

-H2-WHAT  THIS  CHAPTER  COVERS 

This  chapter  outlines  how  to  prepare  your  application  for 
distribution  and  support  it  once  it  goes  out.  The  topics  covered 
are: 

-o-Preparing  user  documentation 
-o-Preparing  distribution  disks 
-o-Supporting  your  application-ENDLIST- 
-H2- PREPARING  USER  DOCUMENTATION 

Good  user  documentation  is  essential  to  a  complete  application 
package.  Even  if  you  install  the  system  and  provide  initial 
on-site  training,  you  won't  always  be  available  to  answer 
questions  and  train  additional  users.  The  documentation  is  the 
trainer  you  leave  behind.  As  you  write  the  documentation,  keep  in 
mind  that  the  better  it  is,  the  less  time  you'll  spend  answering 
users'  questions. 

A  basic  documentation  package  should  include: 

-o-Instructions  on  how  to  install  and  start  the  application 

-o-A  simple  tutorial 

-o-A  comprehensive  reference 

-o-A  list  of  defined  function  keys 

-o-A  list  of  error  messages 

-o-A  table  of  contents 

-o-An  index-ENDLIST- 

The  tutorial  should  explain  how  to  navigate  the  application  and 
provide  step-by-step  exercises  which  perform  basic  program 
operations.  This  book  does  not  need  to  be  comprehensive.  In  fact, 
too  much  detail  in  a  tutorial  distracts  users  from  the  new 
techniques  they  are  trying  to  learn.  The  exercises  should  be 
simple  enough  to  leave  users  with  a  sense  of  confidence  that  they 
can  master  your  application.  However,  you  might  want  to  graduate 
the  difficulty  of  the  exercises,  letting  users  figure  out  steps 
in  later  ones  that  they  should  have  already  learned  earlier. 
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The  reference  should  be  a  comprehensive  description  of  your 
application:  its  navigation  keys,  menus  and  menu  options,  limits 
and  defaults,  and  other  technical  information.  The  reference  to 
the  menus  should  follow  the  same  order  as  the  menu  tree.  Cover 
function  keys,  commands,  and  error  messages  separately  in 
alphabetical  order. 

For  a  large  application,  you  might  also  want  to  provide  a  guide 
organized  by  task  rather  than  menu  option.  This  saves  users  from 
scanning  menus  when  they  know  what  task  they  want  to  perform,  but 
not  which  menu  option  accomplishes  it. 

Always  provide  a  table  of  contents  and  an  index  with  the 
documentat ion . 

To  learn  more  about  how  to  write  good  user  documentation,  read 
Softwords,  Hardwords :  A  Common  Sense  Guide  to  Creative 
Documentation,  by  Lucia  McKay,  Ashton-Tate  Publications,  1984. 

-H2  -  PREPARING  DISTRIBUTION  DISKS 

The  dBASE  IV  RunTime  interpreter  can  execute  compiled  dBASE  code. 
This  permits  you  to  distribute  your  application  to  clients  who  dc 
not  own  dBASE.  dBASE  IV  provides  two  utilities  to  help  you 
prepare  distribution  disks,  BUILD  and  DBLINK. 

BUILD  is  a  stand-alone,  menu-driven  utility  that: 

-o-Compiles  your  program  (.prg  and  .prs)  source  files  into  object 
(.dbo)  files 

-o-Optionally  invokes  the  DBLINK  utility  to  link  the  object  file: 
into  a  single  RunTime  file 

-o-Optionally  copies  all  the  application  files  and  the 
single-user  RunTime  interpreter  to  distribution  disks. -ENDLIST- 

DBLINK  is  a  stand-alone  utility  that  lets  you  group  compiled 
object  files  into  a  single  file.  DBLINK  condenses  the  size  of 
your  application  and  makes  it  run  more  efficiently  by  linking  al] 
the  module  programs  in  one  unit. 

See  the  Runtime  and  Utilities  book  for  instructions  on  how  to  us« 
RunTime,  BUILD,  and  DBLINK. 

You  might  want  to  provide  users  of  your  application  a  turnkey 
system.  A  turnkey  system  presents  inexperienced  operators  the 
simplest  possible  program  startup.  When  the  user  inserts  the 
RunTime  disk  and  turns  on  the  computer,  your  application  starts 
automatically,  just  like  turning  a  key  to  start  a  car. 

To  create  a  turnkey  system  for  your  application,  add  the 
following  command  at  the  end  of  the  user's  DOS  Autoexec.bat  file 
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~M~ DBASE  A: <f ilename>~N~ 


You  can  edit  the  Autoexec.bat  file  with  the  dBASE  IV  program 
editor  or  any  standard  editor.  The  <filename>  should  be  the  name 
of  your  main  program  file  —  the  one  you  use  when  you  DO  your 
application. 

-NOTE-Use  the  drive  label  B:  if  your  application  will  be  running 
on  a  dual  floppy  disk  system.  Also  remember  to  SET  DEFAULT  TO  B 
in  the  setup  area  of  your  program  or  include  DEFAULT=B  in  the 
user's  Config.db  file,  to  ensure  that  your  system  will  find  its 
database  files . -ENDBOX- 

-H2- SUPPORTING  YOUR  APPLICATION 

Work  on  an  application  doesn't  end  when  you  distribute  the  disks 
to  your  client.  To  maintain  a  reputation  as  a  developer  who 
stands  behind  his  work,  you  must  providing  adequate  support  to 
users  of  your  applications.  Basic  support  includes: 

-o-Installing  the  application  for  the  first  set  of  users 

-o-Training  the  first  set  of  users  in  how  to  use  the  application 

-o-Providing  telephone  support  for  users  of  the  application 

-o-Correcting  bugs  discovered  by  users 

-o-Revising  the  application  to  a  limited  extent-ENDLIST- 

There  are  limits  to  your  support  responsibilities,  however.  Just 
as  hardware  products  have  a  warranty  that  expires,  you  don't  have 
to  support  a  product  indefinitely  at  no  additional  charge.  If 
your  Initial  contract  specifies  clearly  what  the  application  will 
do,  cover  further  design  changes  under  a  new  contract.  Similarly, 
you  might  limit  free  telephone  support  and  training  to  a 
reasonable  period  of  time  after  you've  distributed  the  disks. 

Whatever  your  policies  and  procedures  are,  be  sure  to  explain 
them  to  clients  in  advance. 

-H2 -OTHER  ASHTON-TATE  PROGRAMMING  PUBLICATIONS 

There  are  several  Ashton-Tate  publications  that  you  might  find 
helpful  as  you  gain  dBASE  programming  experience: 

-o -Ashton-Tate  Magazine  is  a  monthly  journal  ....  [Message  left 
for  Pat  Matthews] 

-o-dBASE  III  PLUS  to  dBASE  IV:  The  Language  Bridge  Book  by  Adam 
Green  (fall  of  1988)  will  be  particularly  useful  to  programmers 
with  dBASE  III  PLUS  experience 
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-o-dBASE  IV  SQL  User's  Guide  by  Jack  L.  Hursch,  Ph.D.  and  Carolyn 
J.  Hursch,  Ph.D.  (fall  of  1988)  will  help  you  incorporate  SQL 
capabilities  into  your  applications . -ENDLIST- 

To  subscribe  to  the  Ashton-Tate  Magazine ,  call  the  Ashton-Tate 
Subscription  Service  at  (619)  747-1666.  To  order  Ashton-Tate 
publications  and  learn  about  new  publications,  call  Ashton-Tate 
at  (213)  329-8000. 
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About  RunTime 


Once  you've  mastered  dBASE  IV  programming,  you  might  want  to  distribute 
stand-alone  application  programs.  This  manual  helps  you  develop  stand¬ 
alone  programs  for  use  with  the  RunTime  interpreter. 

This  manual  will: 

■  Describe  and  tell  you  how  to  use  RunTime,  including  several  tips 

■  Describe  in  detail  how  to  run  the  BUILD  and  DBLINK  utilities 

RunTime  is  capable  of  interpreting  object  programs  from  the  dBASE  IV 
compiler.  Single  or  unlimited  multi-user  capability  is  provided  by  the  same 
RunTime  interpreter. 


NOTE 

RunTime  will  run  on  a  dual  floppy  system.  The  programs  on  the  three 
original  RunTime  disks  are  grouped  so  that  disk  1  is  removable,  disk  2 
stays  in  the  drive,  and  disk  3  contains  infrequently  used  routines.  For 
example,  a  basic  text  editor  is  provided  on  disk  3. 


What  Is  a  RunTime  Application? 

RunTime  is  a  program  that  executes  your  compiled  code,  enabling  you  to 
distribute  stand-alone  applications  developed  in  dBASE  IV.  There  are  two 
utility  programs,  BUILD  and  DBLINK,  provided  to  help  you  create  an  appli¬ 
cation  you  can  distribute.  BUILD  automatically  uses  the  dBASE  IV  COMPILE 
command  on  your  program  (  prg,  prs,  .fmt)  files.  As  a  side  benefit,  the  com¬ 
piled  code  ensures  that  others  cannot  tamper  with  your  program.  BUILD  can 
invoke  DBLINK  if  you  wish  to  link  all  the  dependent  object  files  into  one 
executable  file. 

If  you  decide  not  to  use  DBLINK,  you  must  make  sure  all  the  files  called  by 
your  application  are  on  the  disk.  Some  developers  prefer  having  multiple 
unlinked  files  so  they  only  have  to  change  and  distribute  the  modified  mod¬ 
ulo.  By  using  DBLINK,  you  end  up  with  far  fewer  files  on  your  distribution 
disk.  However,  every  time  you  make  a  change  to  your  application,  you  must 
link  all  your  files  again. 

'too  csa  run  the  compiled  or  linked  files  with  dBASE  IV  or  any  compatible 
Allure  version.  You  cannot  use  an  earlier  version  of  dBASE. 
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If  your  customers  do  not  own  dBASE  IV,  you  can  deliver  your  program  with 
a  special  version  of  dBASE  IV  called  RunTime.  RunTime  is  functionally 
equivalent  to  dBASE  IV;  however,  it  can  only  run  files  compiled  by 
dBASE  IV  or  linked  with  DBLINK. 

Requirements  For  Creating  A  RunTime  Application 

RunTime  Utilities 

The  BUILD  utility  is  made  up  of  the  following  four  files.  All  of  the  files  must 
be  in  the  same  subdirectory. 

■  Build.exe  —  This  is  the  only  file  you  need  to  call. 

■  Build. res  —  Called  by  Build.exe 

■  Buildx.exe  —  Called  by  Build.exe 

■  Buildx.res  —  Called  by  Buildx.exe 

The  DBLINK  utility  is  made  up  of  two  files.  Both  files  must  be  in  the  same 
sub-directory. 

■  Dblink.exe  —  Called  by  Build.exe 

■  Dblink.res  —  Called  by  Dblink.exe 


RunTime 

The  RunTime  files  that  must  be  made  available  for  each  application  are: 

■  Runtime.exe 

■  Runtimel.ovl 

■  Runtime2.ovl 

■  Runtime3.ovl 

■  Runtime4.ovl 

■  dBASEl.res 

■  Protect.ovl 


Support  for  the  PROTECT  command  is  in  the  Protect.ovl  file.  If  you  do  not 
want  your  user  to  change  field  access  levels,  do  not  copy  Protect.ovl  to  your 
distribution  disk.  Also,  do  not  include  the  command  PROTECT  in  the  source 
code.  RunTime  supports  encrypted  data  regardless  of  whether  Protect.ovl  is 
provided. 
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Are  You  Ready  For  RunTime? 


Before  using  RunTime,  you  should  be  an  experienced  dBASE  IV  program¬ 
mer.  You  should  also  understand  the  basics  of  DOS  file  management,  espe¬ 
cially  how  to  work  with  directories.  Your  program  should  already  be  written, 
tested,  and  debugged.  You  should  only  work  with  RunTime  when  you  have  a 
finished  program,  one  that  has  been  thoroughly  tested  and  that  you  feel  is 
ready  for  the  real  world. 

Remember  that  this  is  your  program  and  you  must  stand  behind  it 
completely.  You  are  responsible  for  its  documentation  and  technical  support. 


NOTE 

Ashton-Tbte  will  not  offer  assistance  to  users  of  your  application  pro¬ 
grams.  You  must  provide  this  yourself.  Ashton-Thte’s  Software  Support 
center  will  direct  all  calls  regarding  your  program  to  you. 


RunTime  Restrictions 

RunTime  will  not  support  the  following  dBASE  IV  commands: 

■  Ampersand  substitution  of  command  verbs 

■  ASSIST 

■  COMPILE 

■  CRE ATE/ MODIFY  FILE 

■  CREATE/ MODIFY  LABEL 

■  CREATE/  MODIFY  REPORT 

■  CREATE/  MODIFY  QUERY 

■  CREATE/  MODIFY  SCREEN 

■  CREATE/MODIFY  STRUCTURE  (full-screen) 

■  CREATE/MODIFY  VIEW  (full-screen) 

■  HELP 

■  HISTORY 

■  Menu-driven  SET 

■  SET  DEBUG 

■  SET  DOHISTORY 

■  SET  ECHO 

■  SET  HISTORY 

•  SET  INSTRUCT 

•  SET  SQL 
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■  SET  STEP 

■  SET  TRAP 

■  SUSPEND 


How  to  Use  RunTime 

To  prepare  stand-alone  applications,  use  the  BUILD  utility  outside  of 
dBASE  IV.  You  must  make  sure  that  all  the  program  files  for  your  applica¬ 
tion,  whether  prg  or  .prs,  are  in  the  current  directory.  At  the  system  prompt, 
type  BUILD.  Then,  at  the  Compile  {filename} prompt,  enter  the  filename  of 
the  main  module  of  your  application.  See  Chapter  3,  “Thing  BUILD,”  for  a 
complete  discussion  of  the  options  available  to  you. 


NOTE 

RunTime  provides  for  an  unlimited  number  of  users  and  no  special 
installation  is  required.  It  is  your  responsibility  to  code  your  applica¬ 
tions  for  multi-user  access. 


RunTime  is  invoked  by  having  the  user  type  RUNTIME  <  filename >  at  the 
system  prompt.  RunTime  will  try  to  find  and  execute  a  dbo  file  of  this  name. 
If  the  speciSed  Hie  is  not  found,  RunTime  will  return  to  the  system  prompt. 

Alternatively,  you  may  type  RUNTIME  without  specifying  a  filename.  The 
disk  is  then  searched  for  the  default  filename  Dbruncmd.dbo. 


Documentation  and  Technical  Support  for  Your  Program 

You  are  responsible  for  your  programs.  Make  sure  that  you  distribute  all  the 
necessary  information  to  run  your  application.  Ashton-Tate  cannot  provide 
support  for  your  distributed  applications. 
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DBLINK 


| 


DBLINK  is  a  stand-alone  utility  that  links  several  dBASE  IV  object  files  into 
one  single  object  file.  You  would  use  BUILD  if  you  needed  your  output  to  be 
divided  into  several  RunTime  object  files. 

This  means: 

■  Easier  development,  as  the  entire  application  does  not  have  to  be  recom¬ 
piled  if  only  one  or  two  program  modules  are  changed. 

■  Faster  execution  of  the  final  application,  as  there  is  only  one  file  that  has 
to  be  accessed  by  the  RunTime  engine. 

■  Less  disk  space  for  the  final  application,  as  there  is  only  a  single  object 


Using  DBLINK 

To  use  DBLINK,  type  DBLINK  <  input  filename  >  /L  and  press  ♦*. 


<  input  filename  >  is  the  name  of  the  main  module  of  your  application. 
DBLINK  goes  through  this  file  identifying  all  the  command  and  procedure 
files  that  it  calls.  It  then  goes  through  each  of  these  called  files  looking  for 
additional  called  command  and  procedure  files.  DBLINK  will  repeat  this 
procedure  until  all  called  command  and  procedure  files  are  identified.  The 
main  module  and  all  command  and  procedure  files  that  have  been  found  are 
then  linked  into  one  object  file. 


NOTE 

Make  sure  you  have  the  files  Dbfink.exe  and  Dblink.res  in  the 
directory. 


M  WARNING 

Only  explicit  external  file  references  are  found  by  DBLINK  and 
BUILD.  Macros  that  contain  filenames,  like  DO  Jtmemvar,  are  not 
expanded.  Consequently,  these  files  will  not  be  referenced  by  the 
utilities. 
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The  resulting  object  file  has  the  same  name  as  the  main  module,  but  with  a 
.dbo  extension.  The  original  is  renamed  with  a  .bak  extension. 

All  input  files,  including  the  main  module,  must  be  compiled  with  dBASE  TV's 
COMPILE  or  DO  commands  before  being  linked.  If  an  input  file  is  not  found 
or  is  not  an  object  file,  it  will  not  be  linked.  The  original 
DO  <  filename  >  command  will  still  be  in  the  linked  calling  file.  This  can 
slow  the  program  execution  time. 

Because  DBLINK  combines  object  files,  you  can  include  compiled  format 
and  .prs  (SQL  program)  files  within  your  finished  application. 

NOTE 

You  cannot  combine  format  and  prs  files  into  one  large  .prg  file 
at  the  source  code  level.  They  must  first  be  compiled  and  then  linked. 
DBLINK  allows  you  to  combine  mixed  file  types,  compiled  by 
dBASE  IV,  into  .dbo  files. 

The  maximum  size  and  number  ofprocedures  supported  by  DBLINK  are  the 
same  as  for  .dbo  files  throughout  JbBASE  IV.  This  means  you  may  have  up  to 
65,520  bytes  of  compiled  code  per  procedure,  with  a  maximum  of  1,170  pro¬ 
cedures  per  .dbo  file.  The  actual  number  of  procedures  that  can  be  accessed 
depend^ on  the  free  RAM  available  in  the  operating  environment. 


© 


The  /L  Option 

This  option  creates  a  document  listing  the  files  that  were  linked  and  the  pro¬ 
grams  that  are  referenced  but  not  linked.  This  information  is  placed  in  a  text 
file  with  the  same  name  as  the  main  source  file,  but  with  a  .txt  extension. 


Messages 

If  a  referenced  file  cannot  be  located  by  DBLINK,  the  message  Cannot  open 
<  input  filename  >  File  <  input  filename  >  does  not  exist  appears. 


Upon  the  completion  of  the  linking  process  the  message  Press  RETURN  to 
proceed  appears.  This  will  take  you  back  to  either  the  DOS  prompt  or 


BUILD. 
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Using  BUILD 


BUILD  is  the  stand-alone  utility  that  automatically  compiles  and  optionally 
links  your  programs  for  use  by  dBASE  IV  or  RunTime. 


NOTE 

You  must  run  BUILD  from  the  DOS  prompt  as  it  invokes  dBASE  IV. 
If  you  try  to  run  BUILD  from  the  dot  prompt,  the  DOS  Insufficient 
Memory  error  message  appears. 


BUILD  has  three  basic  functions: 

■  Parsing  all  program  Gles  regardless  of  extension.  This  means  .prg,  prs, 
rpt,  and  .lb!  files,  and  any  other  file  that  is  executed  by  your  main  pro¬ 
gram.  BUILD  will  use  dBASE  IV  to  compile  the  main  calling  file,  all 
dependent  files,  and  user-defined  functions. 

■  Optionally,  invoking  the  DBLINK  utility  to  link  together  all  dependent 
object  files  into  one  RunTime  file. 

■  Copying,  at  your  option,  all  the  RunTime  application  Gles  (including 
such  things  as  data  Gles,  views,  and  indexes,  as  well  as  the  RunTime 
interpreter)  to  a  target  directory  or  series  of  disks. 


Getting  Ready 

Before  you  run  BUILD  you  should  do  the  following: 

■  Make  sure  that  all  the  BUILD  utility  Gles  are  in  the  dBASE  IV  directory 
and  that  this  directory  name  appears  in  the  DOS  path.  The  necessary  Gles 
are: 

■  Build.exe 

■  Buildx.exe 

■  Build.res 

■  Buildx.res 

■  Copy  all  necessary  application  Gles  to  the  current  directory.  This  does 
aot  have  to  be  the  dBASE  IV  directory. 

•  If  DBLINK  is  to  be  used,  make  sure  that  it  is  in  the  dBASE  IV  directory. 
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■  If  the  output  files  are  to  be  copied  into  a  directory,  make  sure  that  direc¬ 
tory  exists.  If  the  output  files  are  being  sent  directly  to  floppy  disks, 
make  sure  that  they  are  formatted. 

■  If  the  application  exceeds  the  maximum  number  of  command  files 
allowed  by  DBLINK,  or  the  application  is  too  large  to  fit  on  a  floppy 
disk,  create  the  text  file  Build. mod.  This  file  is  discussed  in  detail  in  the 
"Using  Build. mod”  section  in  this  chapter.  Note  the  maximums  below: 

■  There  is  a  maximum  of  65,520  bytes  of  compiled  code  per  procedure 

■  There  is  a  maximum  of  65,520  bytes  of  compiled  code  within  a  rela¬ 
tive  branch  such  as  a  DO  WHILE  loop. 

■  There  is  a  maximum  of  32  active  dbo  files  allowed.  A  file  is  active  if 
it  can  be  accessed  by  a  RETURN  or  if  it  is  the  file  named  in  a  SET 
PROGRAM  or  SET  SQLPROGRAM  command. 

The  modular  outputs  will  each  have  the  filename  of  the  senior  command  file 
as  listed  in  Build. mod 


Running  BUILD 

At  the  DOS  prompt,  type  C:BUILD  and  press 
The  screen  shown  in  Figure  2-1  appears. 


Rgure  2-1  The  BULD  screen 

You  mtj  choose  either  of  the  two  menus  or  exit  at  this  point. 
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The  BUILD  Menu 


Figure  2-2  The  BULD  menu 


The  Compile  {filename} option  accepts  the  filename  of  the  main  module  of 
your  application.  You  do  not  have  to  include  the  .prg  or  .prs  extension.  After 
pressing  press  Shift-FI  to  obtain  a  list  of  files  in  the  current  directory. 
BUILD  assumes  that  the  files  to  be  parsed  and  compiled  are  in  the  current 
directory. 

The  Link  yes/no  option  tells  BUILD  whether  or  not  to  invoke  the  LINK  util¬ 
ity  following  the  compiling  of  your  application  files.  The  default  is  yes. 

The  Oatpat  destination  submenu  determines  the  destination  of  the  finished 
application  with  all  its  associated  files.  The  submenu  options  are  Drive  {} 
and  Path  {}  If  they  are  left  blank,  your  compiled  and  linked  application  files 
will  be  put  in  the  current  directory  only.  If  these  options  are  filled  in,  the 
output  of  the  BUILD  utility  will  be  placed  in  the  target  directory. 


You  may  also  specify  the  floppy  disk  drive  if  you  wish  your  application  to 
output  directly  to  floppy  disks.  Or  you  may  specify  another  subdirectory  in 
order  to  consolidate  ail  your  application  files.  This  is  useful  if  your  source 
files  are  in  different  subdirectories. 


NOTE 

DBUNK  will  rename  your  original  Gle  with  a  .bac  extension. 


Tha  final  option  is  Perform  BUILD,  which  starts  the  BUILD  program. 
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Options  Menu 


Figure  2-3  The  Optione  menu 

The  Search  for  aew  functions  yes/no  option  instructs  BUILD  to  search  for 
potential  user-defined  functions  (UDFs)  that  may  be  identical  to  dBASE  IV 
functions.  Applications  that  have  been  developed  outside  of  dBASE  IV  may 
have  existing  UDFs  that  duplicate  current  dBASE  IV  keywords  (for  example, 
SIN()).  These  UDFs  are  considered  redundant  and  will  not  be  executed; 
instead,  the  new  dBASE  IV  functions  will  be  used.  A  list  of  your  functions 
that  duplicate  the  new  dBASE  IV  functions  will  appear. 

The  default  is  no.  If  you  answer  yes  to  this  option,  BUILD  will: 

■  Identify  all  functions  that  duplicate  a  dBASE  IV  keyword. 

■  Provide  you  with  the  message  UDF  <  filename >  may  be  redundant.  If 
you  have  a  UDF  by  this  name,  it  will  not  be  compiled,  and  therefore 
never  executed.  BUILD  will  provide  a  list  of  suspect  UDFs  that  you  must 
check. 

The  Accept  only  RunTime  commands  determines  whether  dBASE  IV  issues 
an  error  message  if  an  illegal  RunTime  command  is  parsed.  The  default  is 
yes. 

The  Include  file  types  option  displays  a  list  of  all  the  dBASE  IV  file  types 
followed  by  yes/no.  Use  this  option  to  determine  which  file  types  are 
included  in  the  final  copy  operation  that  builds  the  RunTime  application  set. 
The  default  is  yes.  This  option  has  no  effect  on  the  compile  and  link  process; 
it  only  affects  the  copy  process.  This  is  useful  when  recompiling  because 
only  those  files  that  have  been  changed  need  to  be  copied  over. 
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The  Prial  menage*  to ...{}  option  it  an  enumerated  field  directing  the  mes¬ 
sage  output  of  BUILD.  The  File  option  sends  messages  to  a  file  named 
Build.txt.  Printer  and  File  both  echo  messages  to  the  screen.  Screen  is  the 
default. 


The  Copy  single -aser  RunTime  yes/no  option  directs  BUILD  to  copy  an 
installed  version  of  single-user  RunTime  to  the  finished  application  during 
RunTime. 


NOTE 

If  you  choose  ao ,  you  will  not  automatically  get  multi-user  RunTime. 
Single-user  RunTime  can  simply  be  copied  to  your  application  disk. 
Multi-user  RunTime  must  be  installed  for  every  application.  See  the 
section  on  multi-user  in  this  manual  for  more  information  about  this 
option. 


The  Locate  RunTime  source  directory  option  displays  a  submenu  through 
which  you  can  fill  in  the  drive  and  path  containing  the  installed  single-user 
RunTime.  The  default  is  set  to  the  installation  defaults  in  DBSETUP. 


Using  Build.mod 

Build. mod  is  a  text  file  containing  the  filenames  of  command  files  that  begin 
application  sub-modules.  You  only  have  to  specify  the  filename  and  do  not 
have  to  include  the  file  extension.  The  name  of  the  application’s  main  mod¬ 
ule  must  still  be  entered  in  the  Compile  option  of  the  Build  submenu.  If 
Build.mod  is  not  found  in  the  current  directory,  BUILD  will  not  segment  the 
application. 

BUILD  parses  the  main  application  module  and  builds  a  file  of  external  com¬ 
mand  file  references.  It  checks  for  files  listed  in  Build.mod  but  not 
referenced  in  the  application.  If  such  files  are  found,  the  message  Warning: 
Module  <  filename >  not  referenced  in  application  will  appear  and 
BUILD  will  continue. 

Every  object  file  corresponding  to  a  file  in  Build.mod  receives  a  temporary 
file  extension,  .xxx,  which  DBLINK  cannot  recognize.  The  DBLINK  utility  is 
then  called  and  links  together  all  object  files  it  can  recognize. 

BUILD  goes  through  the  list  of  files  in  Build.mod  and  changes  the 
corresponding  object  file  to  the  recognizable  extension  (.dbo).  This  file  and 
its  subsidiary  files  are  then  processed  by  DBLINK  and  control  is  returned  to 
BUILD  so  that  the  next  file  in  Build.mod  can  be  processed. 
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Application  Modules  Created  by  Build.mod 

The  compiled  and  linked  application  modules  have  the  filename  of  the  com¬ 
mand  file  listed  in  Build.mod.  They  will  have  the  normal  .dbo  extension. 


Figure  3-1  Programs  in  a  typical  application 

If  you  create  a  Build.mod  file  that  contains  three  program  names  from  the 
application,  Build.mod  will  create  four  linked  and  compiled  modules:  the 
three  programs  and  all  their  subsidiary  programs,  plus  the  main  program 
and  its  subsidiary  programs  which  have  not  already  been  incorporated. 


Suppose  Build.mod  contains  the  filenames  Menul,  Module4,  and  Procfile, 
and  Mainmenu  was  the  filename  specified  at  the  compile  option.  The  four 
modules  described  below  would  be  created: 

■  Mainmenu. dbo 

This  is  made  up  of  the  files: 

Mainmenu. prg  Menu2.prg  Module3.prg  Program07.prg  Program08.prs 
Program  09. prg 

■  Menul. dbo 

This  is  made  up  of  the  files: 

Menul. prg  Modulel.prg  ProgramOl.prg  Program02.prs  Program 03.prg 
Module2.prs  Program 04. prg  Program 05. prs  Program 06. prg 

■  Module4.dbo 

This  is  made  up  of  the  files: 

Mod»le4.prg  Program  10. prs  Program  1 1. prs  Program  12. prs 
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■  Procfile.dbo 

This  is  made  up  of  the  files: 

Procfile.prg  Procl.prg  Proc2.prg  Proc3.prg  Proc4.prg 


BUILD  Output 

BUILD  will  output  a  compiled  and  linked  application  ready  to  be  given  to 

your  users.  It  can  include: 

■  dbo  files  for  all  prg  and  prs  files  used  in  the  application  in  the  same 
directory  as  the  source  files. 

■  If  LINK  was  invoked,  the  dbo  file  with  the  same  prefix  as  the  application 
main  module  will  include  the  linked  files. 

■  The  application  files  on  disk  and,  if  requested,  the  single-user  RunTime 
and  batch  file  for  installation. 

■  Output  messages  to  the  screen,  printer,  or  file. 

Unless  an  alternate  path  is  specified,  BUILD  will  write  all  output  files  to  the 

current  drive  and  directory. 
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Copyright  ®  Ashton-Tate  Corporation  1988 
As  an  unpublished  work.  All  Rights  Reserved. 

Use  of  the  software  contained  in  this  package  has  been  provided  under 
a  Software  License  Agreement.  Please  read  it  thoroughly.  In  summary, 
you  may  not  make  copies  ef  the  software  except  as  specifically  permit¬ 
ted  under  the  Software  License  Agreement.  You  may  use  the  software 
only  on  a  single  terminal  or  a  single  workstation  of  a  computer  (or  its 
replacement):  accordingly,  you  must  license  a  separate  copy  for  each 
terminal  or  workstation  where  you  want  to  use  the  software  or  use  the 
multi-user  version  on  the  permitted  number  of  workstations  as  set  forth 
in  the  multi-user  license  agreement. 

Note:  Unauthorized  use  of  the  software  or  of  the  related  materials  can 
result  in  civil  damages  and  criminal  penalties. 

The  software  and  related  materials  in  this  package  are  licensed  with  a 
Limited  90-Dav  Warranty.  Other  than  the  limited  warranties  that  are 
expressly  stated  therein,  Ashton-Tate  makes  no  other  warranty, 
express  or  Implied,  to  you  or  any  other  person  or  entity.  We  will  not 
be  liable  for  incidental,  consequental  or  other  similar  damages.  In 
no  event  will  our  liability  for  any  damages  ever  exceed  the  price 
paid  for  the  license  to  use  the  software,  regardless  of  any  form  of 
the  claim.  You  may  have  other  rights  which  vary  from  state  to  state. 

Ashton-Tate  and  the  Ashton-Tate  logo,  dBASE,  dBASE  II,  and  dBASE  III 
are  registered  trademarks  of  Ashton-Tate  Corporation.  dBASE  III  PLUS. 
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and  is  used  under  license  from  Chartmasters,  Inc.  Chartmasters  is  a 
registered  trademark  of  Chartmasters,  Inc. 
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The  Purpose  of  a  Template 

The  dBASE  IV  Template  Language  enables  you  to  generate  either  documen¬ 
tation  or  program  versions  of  objects  designed  on  the  reports,  forms,  or  labels 
design  screens,  or  with  the  dBASE  IV  Applications  Generator. 

Just  as  a  tailor  uses  cloth  and  a  pattern  to  make  a  suit,  dBASE  IV  provides 
you  with  design  objects  (the  cloth)  and  templates  (the  pattern)  to  make  a  fin¬ 
ished  text  file.  Using  dBASE  IV  design  screens,  you  can  create  the  type  of 
material  you  want  to  work  with.  The  template  is  the  pattern  that  determines 
how  the  material  will  be  cut. 


The  design  objects  stored  in  their  respective  files  are  the  cloth.  The  compiled 
template  stored  in  a  .gen  file  is  the  pattern,  and  the  resulting  text  file  is  the 
suit.  A  tailor,  by  changing  the  pattern,  can  use  the  same  cloth  to  make  a  dress 
or  a  shirt.  You  can  use  the  same  object  files  and  by  changing  the  template, 
create  a  dBASE  program  version  of  the  object  or  an  English  language  descrip¬ 
tion  of  the  design.  The  same  object  using  a  different  template  can  be  described 
in  any  language  you  wish. 

Because  a  template  is  a  pattern  to  be  used  by  the  dBASE  IV  design  tools,  you 
must  have  a  working  knowledge  of  the  structure  of  design  objects  and  of  the 
dBASE  language  if  you  are  writing  or  modifying  templates. 

The  template  provides  the  pattern  for  the  Applications  Generator,  and  the 
reports,  forms,  and  labels  design  screens  to  use  in  the  creation  of  an  output 
text  file.  This  file  is  a  standard  ASCII  file  containing  merged  information  from 
the  template  file  and  the  object  design  files.  Depending  on  the  template  used, 
the  text  file  can  serve  as  a  description  of  the  design  object  or  as  a  programmed 
version  of  the  design  object. 
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Figure  1-1  Design  objects 


Uses  for  Templates 

The  Template  Language  gives  you  control  over  how  your  design  objects  will 
run.  The  tailor  uses  different  patterns  for  different  size  shirts,  so  you  may 
want  to  use  different  templates  to  fit  your  design  objects  to  different  equip¬ 
ment.  Besides  adding  help  text,  or  embedded  code  to  operate  specific  hard¬ 
ware,  you  can  position  the  object  and  determine  its  appearance. 

For  example,  you  may  want  your  labels  to  always  include  a  return  address 
in  bold.  Using  the  Template  Language,  you  could  modify  the  template  to  pro¬ 
vide  this  capability.  Or  you  may  want  to  use  labels  for  pricing  or  inventory 
control,  and  so  decide  to  automatically  add  department  identification  or  a 
bar  code  to  each  label. 
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Prototyping 

The  dBASE  IV  environment  provides  you  with  many  tools,  and  the  template 
is  used  with  these  tools.  The  Applications  Generator  and  the  reports,  forms, 
and  labels  design  screens  are  all  prototyping  tools  that  help  you  design  the 
particular  objects  you  want. 

The  reports,  forms,  and' labels  design  screens  provide  you  with  a  work  sur¬ 
face  related  to  their  particular  type  of  object.  You  specify  the  design  of  the 
object  and  then  specify  the  particular  attributes  of  the  object. 

The  dBASE  IV  Applications  Generator  is  a  sophisticated  design  tool  for 
combining  many  different  types  of  application  objects  into  a  single  menu- 
driven  application.  You  may  want  to  start  with  a  pop-up  menu  that  has  six 
different  choices.  One  might  display  a  list  of  files,  another  might  call  a 
horizontal-style  menu.  Each  of  the  choices  might  have  specific  help  text  that 
can  be  requested  by  the  user.  All  these  design  choices  are  attributes  of  the 
object.  The  Template  Language  gives  you  access  to  these  attributes  and  the 
elements  that  comprise  them. 


What  Is  a  Template? 

A  template  is  text  with  enclosed  commands  for  formatting,  validating,  and 
inserting  data  into  an  ASCII  file.  This  file  is  the  result  of  the  template's  inter¬ 
action  with  the  elements  of  the  design  object.  If  the  text  consists  of  dBASE  IV 
commands,  the  resulting  ASCII  file  will  be  a  dBASE  program.  If  you  designed 
a  label  on  the  labels  design  screen,  the  supplied  label  template  would  gener¬ 
ate  a  program  to  write  the  labels  of  the  particular  size  and  format  you  chose. 
You  could,  if  you  wished,  modify  the  template  so  that  the  program  included 
the  code  for  a  particular  laser  font,  or  added  an  increasing  serial  number  to 
each  label  as  it  printed. 


//  test. cod 
//  6/20/00 
// 


sample  template 


> 


Comments 


Calculate  the  height  of  a  menu 
(include  "builtindef; 
createCtest.doc");} 
hello  world,  it  is  (dateO) 

Menu  name  is:  (name) 

The  height  is  (row2()-row  1  ()) 
The  width  is  (co!2()-col  I ()} 
(return  0;}  - - 

//  eof:  test. cod  - 


- Introduction 

First  command  segment 

"  Text  followed  by  command  segment 
_Text  followed  by  command  segment 
Text  followed  by  command  segment 
Text  followed  by  command  segment 

- Last  command  segment 

- Blank  line 

- Comment 


Figure  1  -2  Sample  template 
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The  template  outputs  text  from  two  sources:  the  text  that  results  from  tem¬ 
plate  commands,  and  the  text  to  be  output  exactly  as  it  appears.  Template 
commands  are  always  placed  within  braces.  Text  you  wish  to  output  directly 
is  placed  outside  braces.  Text  that  results  from  template  commands  might  be 
the  name  of  the  design  object  or  the  text  of  a  menu  line.  Text  outside  braces 
might  include  dBASE  command  names  or  text  to  be  output  surrounding  the 
result  of  a  command. 


NOTE 

A  template  program  is  generally  used  in  conjunction  with  a  design 
object  file. 


Using  a  Template 

If  you  are  on  the  reports,  forms,  or  labels  design  screen,  a  template  is  auto¬ 
matically  used  with  the  SAVE  menu  option. 

In  the  Applications  Generator,  you  choose  a  template  from  the  GENERATE 
option  of  the  main  menu,  or  select  the  explicit  Generate  quick  application 
from  the  APPLICATION  option  of  the  main  menu. 


The  Form  of  a  Template 

■  Introduction  —  This  is  everything  up  to  the  first  command  indicator 
(the  first  left  brace).  In  the  compiled  template  file,  this  information  is 
not  tokenized  and  can  be  read. 

■  Comments  —  Any  text  on  a  single  line  following  two  right  slash  marks 
(//)  anywhere  within  command  braces,  or  starting  in  column  one  out¬ 
side  of  command  braces.  This  information  is  ignored  by  the  design  gen¬ 
erator.  It  is  for  template  documentation  purposes  only  and  is  not  sent  to 
the  resulting  text  file. 

■  Commands  —  Anything  between  braces  is  considered  a  template  com¬ 
mand  and  will  be  acted  upon.  The  result  of  a  command  or  expression 
is  usually  output  when  the  closing  brace  is  encountered.  A  semicolon 
before  the  closing  right  brace  suppresses  any  values  that  might  have 
resulted  from  the  command.  This  means  the  value  will  not  be  placed 
in  the  output  file. 

■  Text  —  This  is  material  outside  of  the  command  braces  after  the  first  set 
of  braces.  This  material  will  be  printed  to  the  output  file  as  written.  If 
the  text  is  a  dBASE  command,  the  final  output  file  will  be  a  dBASE  pro¬ 
gram  file.  If  the  text  were  English,  German,  or  Spanish,  the  final  output 
file  would  be  an  English,  German,  or  Spanish  text  file. 

Operation  of  a  Template 

A  template  controls  the  contents  and  format  of  the  output  file  by  writing  sel¬ 
ected  text  from  within  the  template,  writing  the  resulting  value  from  a  com¬ 
mand  expression,  or  adjusting  the  output  according  to  command.  Adjusting 
the  output  could  be  anything  from  calling  in  information  from  other  files  to 
changing  the  left  margin  of  the  output  text. 
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Design  Objects 

Templates  transform  design  descriptions  into  programs  or  readable  descrip¬ 
tions  of  the  design. 

Design  information  is  held  in  specific  types  of  files,  depending  on  which 
design  screen  was  used.  These  are  described  below. 


Reports,  Forms,  and  Labels  Design  Object  Files 

In  the  Control  Center,  design  files  for  reports,  forms,  and  labels  are  gener¬ 
ated  by  choosing  the  <  create  >  marker  in  the  associated  panel.  At  the  dot 
prompt,  you  would  use  the  CREATE/MODIFY  command.  The  design  files 
have  the  following  dot  extensions:  reports  (.frm),  forms  (.scr),  and  labels 
(lbl). 


NOTE 

You  must  set  the  DOS  environment  variable  DTL— TRANSLATE  if  you 
wish  to  use  the  stand-alone  dGEN  template  interpreter.  Please  see  the 
section  “The  Template  Language  Interpreter "  in  Chapter  6. 


Applications  Generator  Design  Object  Files 

Applications  Generator  design  files  are  a  set  of  design  files.  The  set  may  be  as 
small  as  one  file  (the  required  application  file),  or  it  may  contain  the  applica¬ 
tion  file  plus  multiple  occurrences  of  any  number  of  the  remaining  types  of 
files. 


NOTE 

A  directory  may  contain  files  for  more  than  one  application,  and  the 
same  file  may  be  used  in  more  than  one  application. 


Table  1-1  Applications  Generator  design  object  file  extensions 


Object 

File  Extension 

The  application 

.app 

Popup 

•Pop 

Bar 

.bar 

File 

.fil 

Structure 

.str 

Values 

.val 

Batch 

.bch 
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Application  Files 

The  .app  file  is  the  start  of  the  overall  application.  It  contains  the  name  of 
the  application  and  other  associated  information  such  as  the  developer's 
name.  Any  application  developed  by  the  Applications  Generator  must  include 
this  file.  One  of  the  design  attributes  of  this  file  is  the  name  of  the  main  menu 
of  the  application.  The  main  menu  can  be  a  popup,  bar  or  batch  file  type. 

This  is  where  the  opening  Choices  of  vour  application  will  appear. 

Each  of  the  remaining  files  holds  specific  menu  design  information.  One  of 
the  design  attributes  for  each  menu  is  whether  it  calls  another  menu,  dis¬ 
plays  certain  records,  or  any  one  of  a  number  of  other  possible  associated 
actions.  In  this  way,  the  application  is  built  up  of  interconnected  objects  with 
their  associated  actions.  When  diagrammed,  this  structure  has  the  look  of  an 
inverted  tree,  as  shown  in  Figure  1-3. 


Your  Application-  APP 


Personnel 

Information 


Popup  Menu-  POP 


-  A  Menu  1 
- B  Menu2 

Level  2 

C  Files 

3 


Menu2-.P0P 


1 .  Reports 
to  screen 

2.  Reports 
to  printer 


Pick  list 
of  ovoiloble 
files 


Choice!- VAL  Choice2-  BCH 


People  who 

Create 

have  worked 

new  file 

for  company 

Report 

more  than 

on  file 

5  years 

Set  flay 

Figure  1-3  Application  design  structure 
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The  Structure  of  a  Design  Object 

Design  data  is  stored  in  files  with  specific  extensions,  one  file  per  object. 
Reports,  forms,  and  labels  each  have  only  one  object  file.  Applications  Gen¬ 
erator  applications  are  made  up  of  any  number  of  instances  of  the  six  types 
of  Applications  Generator  object  files  plus  the  single  .app  file. 


Elements  and  Attributes 

Each  type  of  object  file  holds  information  about  the  design  in  a  structure 
called  an  element.  These  are  some  of  the  types  of  design  elements: 

■  Attribute 

■  Element 

■  Dos_File 

■  Tree 

■  Group 

■  Field 

■  Text 

■  Band 

■  Box 

■  Frame 

■  Ruler 

■  Paragraph 

■  Page-Break 

The  different  dBASE  IV  design  screens  use  different  mixes  of  these  attri¬ 
butes  and  elements.  For  more  detailed  information  on  the  design  screens, 
see  Using  the  Menu  System  and  Using  the  dBASE  IV  Applications  Generator. 
Each  of  these  elements  holds  the  specific  information  about  the  design  in  a 
field  called  attributes.  Examples  of  the  attributes  of  a  particular  design  ele¬ 
ment  are  such  things  as  row  number,  column  number,  and  color.  An  attri¬ 
bute  value  is  therefore  either  a  string  or  a  number. 


NOTE 

Details  of  specific  attributes  may  be  found  in  the  .def  files  provided 
with  dBASE  IV. 


The  relationship  of  object  file,  elements,  and  attributes  is  similar  to  a  data¬ 
base  file,  records,  and  fields.  However,  in  an  object  file  there  may  be  up  to 
several  different  record  types  (called  element  types),  and  each  element  can 
have  a  different  number  of  fields  (called  attributes). 


Not  all  attributes  can  be  found  in  all  elements.  Certain  attributes  are  specific 
to  certain  elements  and  certain  elements  are  specific  to  certain  objects.  The 
value  of  a  design  object's  attribute  or  element  is  referenced  in  a  template  pro¬ 
gram  by  a  symbol  called  a  selector. 
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Cursors 


Accessing  a  specific  object,  element,  or  attribute  within  a  collection  of 
the  same  type  (such  as  the  row  of  a  field  in  a  collection  of  field  elements) 
requires  a  pointer  to  the  particular  member  within  the  collection.  This 
pointer,  called  a  cursor,  holds  a  numeric  value  with  respect  to  the  position 
of  the  specific  member  within  the  collection.  Because  the  value  of  the  cur¬ 
sor  changes  depending  on  the'member  being  indicated,  it  is  considered  a 
variable. 


NOTE 

While  you  can  name  the  cursor  variable  anything  you  like,  you  must 
use  the  correct  keyword  for  the  type  of  cursor. 


There  may  be  multiple  occurrences  of  an  attribute  within  elements.  The 
keyword  for  the  type  of  cursor  is  found  in  the  FOREACH  <  keyword  >  list 
of  attributes  within  the  .def  files  you  include  in  your  compiled  template. 

Selectors 

The  attribute  value  from  the  design  object  may  be  output  to  the  text  file 
when  the  template  and  design  object  are  merged  together.  The  actual  value 
of  an  attribute  is  referred  to  by  the  label  of  the  attribute.  These  label  names 
are  called  selectors  and  may  be  found  in  the  .def  files  provided  with  dBASE  IV. 

The  NAME  selector,  for  example,  refers  to  the  attribute  of  a  design  object 
used  to  identify  it.  If  you  called  your  label  design  object  My— Labels,  the  NAME 
selector  would  return  the  value  My— Labels. 
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For  each  — 
Fld_element 


Attribute  selector  Menu_Act 
holds  0,  which  means  text 
no  action 

Attribute  selector  Fld_Pictur 
holds  "Maintenance" 

Attribute  selector  Menu_Act 
holds  7,  which  means 
add  records 

Attribute  selector  Fld_Pictur 
holds  "Add  a  Record" 


Frame  Level  Attribute 

Menu_Type  =  2  — 
Popup  Menu 


Mainteninct 


Add  a  Record 
Edit  a  Record 
Quit 


Figure  1-4  Object,  element,  attribute  relationship 


Developing  a  Template 

Use  a  standard  text  editor  to  write  the  template  source  file.  This  file  must 
then  be  compiled  using  Dtc.exe  into  a  usable  template  object  file.  See  the 
chapter  on  the  compiler  for  more  information. 

The  next  chapter  is  a  walkthrough  of  a  template  that  documents  an  applica¬ 
tion  designed  using  the  Applications  Generator.  By  reading  through  this  tem¬ 
plate,  you'll  see  how  the  language  works.  The  details  of  the  language  can  be 
found  in  chapters  3  through  6. 
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Walkthrough  of 

Sample 

Template 


Introduction 

This  chapter  gives  you  a  general  walkthrough  of  the  template  program 
Ds_doc.cod.  It  will  give  you  a  feel  for  the  Template  Language  and  explain 
the  suggested  coding  conventions.  Ds_doc.cod  is  the  documentation  tem¬ 
plate  provided  with  dBASE  IV.  The  code  is  written  with  the  idea  of  provid¬ 
ing  readability  for  easy  maintenance.  You  might  want  to  use  this  format  as 
a  standard. 


In  this  printed  version,  text  that  occurs  inside  curly  braces  in  lower  case  is  a 
programmer-created  constant,  procedure  name,  or  label.  It  is  printed  this  way 
as  an  aid  to  learning  the  language.  If  you  print  out  the  template  programs  pro¬ 
vided,  you  will  see  that  lower  case  predominates.  Upper-case  text  includes 
programmer  comments  and  Template  Language  keywords. 


WARNING 

The  line  numbers  are  not  a  part  of  the  listing  and  have  been  added 
as  an  aid  in  reading  this  chapter.  They  should  not  be  used  when  cod¬ 
ing  in  the  Template  Language. 


Purpose 

Ds_doc.cod  is  a  template  to  document  Applications  Generator  applications. 

It  traverses  all  the  Applications  Generator  design  objects  of  the  current  appli¬ 
cation  and  prints  out  the  following: 

■  A  layout  report  for  each  menu 

■  The  setup  for  each  menu 

■  Database/View 

■  Index  files 

■  Comments 

■  Pop-up  menu  generation 
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■  Help 

■  Bar  actions 

■  Menu  prompts 


Walkthrough 

This  walkthrough  shows  you  actual  sections  of  the  template  with  explana¬ 
tions  of  their  purpose  and  syntax. 


has  been  broken  for  printing  purposes. 


NOTE 

Long  code  lines  that  are  a  single  line  in  the  template  may  be  two  lines 
on  the  printed  page.  If  there  is  no  line  number  next  to  the  code  line,  it 


Introductory  Comments 


- 


1 

II 

SAMPLE  TEMPLATE:  WALKTHROUGH 

2 

II 

MODULE  NAME: 

OS  00C. COD 

3 

II 

OATE 

APRIL  15,  1987  2 

43  PM 

4 

II 

DESCRIPTION: 

5 

II 

NOTES 

STAND-ALONE  FILE 

TO  PRODUCE  APPLICATION  DOCUMENTATION 

6 

1/ 

COMPILE  AND  USE 

SEPARATELY 

7 

II 

SYNTAX 

8 

II 

9 

II 

MODULE  CHANGE  LOG 

10 

11 

II 

II 

OATE 

INITIALS 

SHORT  DESCRIPTION 

12 

II 

04/15/87 

KJN 

CREATED  MODULE 

i  13 

II 

06/01/87 

KJN 

USER  DEFINED  FUNCTIONS 

14 

II 

06/04/87 

KJN 

CASE  &  ENUM  C0MMAN0S 

15 

II 

07/02/87 

KJN 

AD0ED  ALL  OBJECT  TYPES 

16 

II 

L 

Lines  1  through  16  are  introductory  comments  that  identify  the  template,  the 
author,  the  date  of  creation,  and  whatever  other  information  is  considered 
necessary  for  maintenance  of  the  code.  Each  comment  line  must  start  with 
a  double  slash  (//).  Comments  are  not  compiled. 
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17 

18  APPLICATION  DOCUMENTATION  TEMPLATE 

19  - 

20  VERSION  1.33 

21  ASHTON-TATE  (C)  1987 

22 


Lines  17  through  22  hold  information  in  ASCII  format  about  the  template 
and  are  passed  through  with  no  modification  to  the  compiled  object  file.  This 
Introduction  will  display  when  the  tokenized  object  file  is  TYPEd  from  the 
system  prompt. 


23  { 


This  is  the  first  left  curly  brace,  signifying  the  start  of  Template  Language 
commands.  The  matching  closing  brace  is  at  the  end  of  line  137.  The  lines 
between  these  two  braces  are  template  commands  to  be  acted  on  by  the 
compiler.  The  results  are  either  used  by  the  code  or  written  to  the  text  file 
that  is  the  result  of  merging  the  design  object  with  the  compiled  template 
program. 


24  INCLUDE  "APPLCTN.DEF" ;  //  APPLICATION  SELECTORS 

25  INCLUDE  "BUILTIN.DEF";  //  BUILT-IN  FUNCTIONS 

26 


A  template  program  can  request  that  the  compiler  call  in  information  from 
other  files  before  it  begins  tokenizing  the  code.  The  standard  template  lan¬ 
guage  functions  are  found  in  the  Builtin.def  file.  The  information  is  requested 
by  using  the  INCLUDE  command.  See  the  “Functions”  chapter  in  this  man¬ 
ual  for  a  description  of  all  the  functions. 

Applctn.def  is  the  file  containing  the  selectors  used  by  Applications  Genera¬ 
tor  designed  objects.  A  selector  consists  of  the  name  of  the  attribute  and  the 
numeric  value  indicating  its  particular  nature.  If  your  application  uses  hori¬ 
zontal  bar  menus,  the  selector  MENU-TYPE  will  hold  the  value  7.  Selectors 
and  their  values  are  contained  in  the  .def  files  provided  with  dBASE  IV. 


NOTE 

The  selectors  for  objects  designed  on  the  reports,  forms,  and  labels 
design  screens  are  found  in  their  own  .def  files.  These  files  are  called 
Report. def,  Form. def,  and  Label. def.  Do  not  INCLUDE  Applctn.def  in 
the  same  template  as  Report.def,  Form. def,  or  Label.def.  The  same 
selector  numbers  are  used  for  different  symbols  and  you  would  get 
incorrect  results. 


TEMPLATE  LANGUAGE 


2-3 


JOBNAME:  No  Job  Name  PAGE:  4  SESS:  8  OUTPUT:  Fri  Jul  29  19:51:41  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpchap2 


Enumerated  Constants 


27 

'  MENU  ACTIONS: 

28 

ENUM  Textno=0, 

// 

0) 

TEXT  (NO  ACTION) 

29 

Open, 

// 

1) 

OPEN  A  MENU 

30 

Brow, 

II 

2) 

BROWSE 

31 

Edit, 

II 

3) 

USE  FORM 

32 

Rept, 

// 

4)  .REPORT 

33 

Labi, 

II 

5) 

LABELS 

34 

Disp, 

II 

6) 

DISPLAY/LIST 

35 

Appd, 

II 

7) 

ADO  RECORDS 

36 

Rcopy, 

II 

8) 

COPY  RECORDS 

37 

Repl , 

II 

9) 

SUBSTITUTE  VALUES 

38 

Dele, 

II 

10) 

MARK  RECORDS  FOR  DELETION 

39 

Reca, 

II 

11) 

UNMARK  RECORDS 

40 

Pack, 

II 

12) 

DISCARD  MARKED  RECORDS 

41 

Indx, 

II 

13) 

GENERATE  INDEX 

42 

Rndx, 

II 

14) 

REINDEX 

43 

Sort, 

II 

15) 

SORT 

44 

Impt, 

II 

16) 

IMPORT  FOREIGN  FILES 

45 

Expt, 

II 

17) 

EXPORT  FOREIGN  FILES 

46 

Fcopy, 

II 

18) 

FILE  COPY 

47 

Oodb, 

II 

19) 

DO  DBASE  PROGRAM 

48 

Indb, 

// 

20) 

INSERT  DBASE  CODE 

49 

Xdos, 

II 

21) 

RUN  DOS  PROGRAM 

50 

Call, 

II 

22) 

LOAD/CALL  BINARY  FILE 

51 

Retu, 

II 

23) 

RETURN  TO  CALLING  PROGRAM 

52 

Quit, 

II 

24) 

QUIT  TO  DOS 

53 

Batch, 

II 

25) 

BATCH  PROCESS 

54 

55  ; 

PI  mac 

// 

26) 

PLAY  BACK  MACRO 

Lines  28  through  54  define  27  enumerated  constants.  The  constant  Textno 
is  assigned  the  value  0,  and  each  constant  in  order  is  assigned  the  next 
sequential  number.  Xdos,  for  example,  is  assigned  the  value  2 1 .  The  com¬ 
piler  assigns  these  values  to  these  names,  and  substitutes  the  value  for  the 
name  in  the  compiled  template. 

In  this  sample,  the  constants  are  listed  one  to  a  line  to  make  the  template 
easier  to  read  and  to  make  the  assigned  numbers  stand  out.  The  numbered 
comments  also  help  you  identify  the  number  each  constant  is  assigned.  The 
sequence  of  numbers  in  this  particular  instance  is  required,  as  the  numbers 
are  the  returned  values  of  the  corresponding  selector. 

These  constants  are  being  used  by  the  programmer  as  mnemonics  for  all 
the  possible  values  of  the  field  selector  MENU_ACT.  Depending  on  the 
choice  made  when  designing  the  application  with  the  Applications  Gen¬ 
erator,  the  field  may  hold  any  number  between  0  and  26.  If  you  look  at 
the  file  Applctn.def  for  MENU_ACT  in  the  field  selector  section,  you  will 
see  the  27  numbers  and  their  meaning.  The  number  21  is  Run  DOS  pro¬ 
gram,  for  example. 
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56 

//  MENU  TYPES 

57 

ENUM  App  =  1 , 

II 

1)  APPLICATION  OBJECT 

58 

Popup, 

II 

2)  POPUP  OBJECT 

59 

F_P1ck, 

II 

3)  FILE  OBJECT 

60 

S  Pick, 

II 

4)  FIELDS  OBJECT 

61 

V_Pick, 

II 

5)  VALUES  OBJECT 

62 

Bar  =  7, 

II 

7)  HORIZONTAL  BAR  OBJf 

63 

II 

6,8  N/A 

64 

Btch  =  9 

n 

7)  'BATCH  OBJECT 

55  ; 

66 

ENUM  Mono  =  0, 

II 

VALUES  TO  COMPARE  VAR 

67 

Cga, 

68 

Ega25, 

69 

Mono43  = 

4, 

70 

Ega43  =  6 

71 

"DISPLAY"  AGAINST 


The  two  instances  of  the  ENUM  command,  lines  57  through  70,  illustrate  the 
ability  to  restart  the  sequence.  Until  otherwise  specified,  the  compiler  would 
keep  adding  one  to  the  previous  number.  Btch  in  line  64  has  to  be  specifi¬ 
cally  numbered  9,  or  the  compiler  would  have  assigned  the  number  8.  These 
numbers  are  found  in  the  selector  file  specified  by  the  earlier  INCLUDE  com¬ 
mand.  This  design  recognizes  that  it  is  easier  to  read  code  that  tests  for  a 
variable  name  rather  than  a  number. 


1  72 

II- 

73 

II 

DECLARE  GLOBAL  VARIABLES 

74 

II- 

75 

VAR  Ask  User, 

// 

VARIABLE  TO  GET  INPUT  FROM  USER 

76 

Barcount, 

// 

COUNTER  FOR  PRINTING  BAR  MENUS 

1  77 

Cnt, 

// 

COUNTER  VARIABLE 

78 

Crlf , 

// 

LINE  FEED  CHARACTER 

79 

Global  View. 

// 

VIEW  FROM  APPLICATION  OBJECT 

80 

Global  Ndx, 

// 

INDEX  STRING  FROM  APPLICATION  OBJECT 

81 

Global  Ord, 

// 

ORDER  STRING  FROM  APPLICATION  OBJECT 

82 

Graph  Prt, 

II 

LOGICAL  VARIABLE  (0,1)  TO  DETERMINE  WHAT 

TYPE  OF  BOX  TO  DRAW 

83 

Line, 

II 

VARIABLE  TO  GRAB  IMAGE  FROM  SCREEN 0 

84 

Linecnt, 

II 

LINE  COUNTER 

85 

Mdoc, 

II 

VARIABLE  TO  STORE  NAME  OF  APPLICATION  OBJECT 

86 

Mspace,  Mspace2. 

,  //  SPACE  VARIABLES  FOR  GRAPHICS  BOX  DUMP 

87 

Org  Appl , 

II 

STORE  APPLICATION  FRAME  NAME  IF  STARTED  ON  ONE 

88 

Pagecnt, 

II 

PAGE  COUNT 

89 

Print  Head, 

II 

LOGICAL  VARIABLE  (0,1)  TO  TEST  PRINTING  OF  HEADING 

90 

Forflag,  Barflag,//  LOGICAL  VARIABLES  FOR  GRAPHICS  BOX  DUMP 

91 

Scrn  Size, 

II 

SIZE  OF  SCREEN  TO  GENERATE 

92 

Display, 

II  TYPE  OF  DISPLAY 

93 

Default  Orv, 

// 

DBASE  DEFAULT  DRIVE 

94 

Temp  Strng, 

II 

VARIABLE  TO  TEMPORARY  STRING 

i  95 

Temp_Strng2; 

n 

VARIABLE  TO  TEMPORARY  STRING 

Lines  75  through  95  declare  variable  names.  In  the  Template  Language,  vari¬ 
ables  must  be  declared  before  they  can  be  used. 
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96  // - 

97  //  ASSIGN  DEFAULT  VALUES  TO  SOME  OF  THE  VARIABLES 

98  // - 

99  Temp_Strng  =  Temp_Strng2  =  AskJJser  = 

100  GlobalJMew  =  Appljiew;  //  SET  GLOBAL  APPLICATION  DBF/VIEW 

101  G1 Obal _Ndx  =  Appl_Ndx;  //  SET  GLOBAL  APPLICATION  NOX 

102  Global_0rd  =  Appl_0rder;  //  SET  GLOBAL  APPLICATION  ORDER 

103  Crlf  =  CHR(IO);  .  -  //  STORE  LINEFEED  CHR(IO)  TO  VARIABLE 

104  Pagecnt  =  1;  II  SET  PAGE  COUNT  TO  1 

105  Di spl ay=NUMSET (_FLGC0L0R) ; 


Here  values  are  assigned  to  some  of  the  variable  names.  They  are  used 
throughout  the  template.  The  single  equal  sign  (  =  )  is  used  for  assignment. 

NUMSET()  in  line  105  is  a  built-in  function  using  a  built-in  ENUM  constant 
—FLGCOLOR.  The  return  values  for  this  function  and  variable  are  in  the 
Builtin.def  file. 


106  //  TEST  SCREEN  SIZE  IF  DISPLAY  >  2  SCREEN  IS  43  LINES 

107  IF  Display  >  Ega25  THEN  Scrn_Size  =  43  ELSE  Scrn  Size  =  25  ENDIF; 

108 

109  Default  Drv  =  STRSET <_DEFDRIVE) ; 

110  IF  F I LEDRI VE (MENU_NAME )  OR  !Default_Drv  THEN 

111  Mdoc  =  ALLTRIM(MENU_NAME) ; 

112  ELSE 

113  Mdoc  =  Oefault  Drv  +  +  ALLTRIM(MENU_NAME) ; 

114  ENDIF 

115  Mdoc  =  UPPER(Mdoc); 

116 


Line  1 1 1  uses  the  ALLTRIM( )  function  with  the  selector  MENU-NAME 
to  eliminate  extraneous  left  and  right  blanks  in  the  string  held  in 
MENU-NAME.  By  the  end  of  line  115,  Mdoc  holds  an  upper-case  trimmed 
copy  of  the  string  held  in  MENU— NAME. 


117  // - 

118  //  CHECK  TO  SEE  IF  DOCUMENTATION  FILE  IS  ALREADY  ON  0ISK 

119  // - 

120  IF  FILEEXIST(Mdoc+" .DOC")  THEN 

121  Retry: 

122  Ask  user  =  ASKUSERI "DOCUMENTATION  FILE  "+Mdoc+" .DOC 

ALREADY  EXISTS. . .OVERWRITE  IT(Y/N) ?" ,"N" ,1 ) ; 

123  IF  NOT  AT (UPPER(Ask_User) ,"YN")  THEN  GOTO  Retry;  ENDIF 


Lines  121  through  123  comprise  a  loop  using  the  GOTO  command  and  a 
label  called  Retry.  The  colon  after  the  word  Retry  on  line  121  declares  that 
word  as  a  label. 
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124  IF  UPPER(Ask  User)  =  "N"  THEN  GOTO  Nogen;  ENOIF 

125  ENOIF 

126  // - 

127  //  ASK  USER  IF  HE  HAS  A  IBM  GRAPHICS  COMPATIBLE  PRINTER 

128  //  GRAPH_PRT  =  0  MEANS  NO  GRAPHICS,  1  MEANS  USE  GRAPHICS 

129  // - 

130  Ask.User  =  ASKUSERC'DO  YOU  HAVE  AN  IBM  GRAPHICS  COMPATIBLE  PRINTER 

( Y/N)  ?"j  "61" ,  1 ) ; 

131  Ret ry2 : 

132  IF  NOT  AT ( UPPER (Ask  User),"YN")  THEN  GOTO  Retry2;  ENOIF 

133  IF  UPPER(AskJJser)  =  "N"  THEN  Graph.Prt=0;  ELSE  Graph_Prt=l;  ENOIF 

134  II - 

135  II  OPEN  OUTPUT  FILE 

136  // - 

137  CREATE (Mdoo"  .DOC") ;  //  OPEN  OUTPUT  FILE) 


The  CREATE  function  opens  a  file  on  disk  to  accept  the  output  from  the 
interpreter  of  the  Applications  Generator.  This  is  the  standard  ASCII  file 
that  is  the  result  of  the  merging  of  information  between  the  results  of  the 
template  commands  and  the  design  object  file.  The  template  being  described 
generates  a  documentation  file.  Other  templates  may  generate  a  program 
file. 


Printing  the  Report 


138  // - 

139  //  PRINT  PAGE  NUMBER  AND  AUTHOR  INFORMATION 

140  II - 

141  PAGE:  {STR(Pagecnt))  DATE:  { LTRIM ( SUBSTRC DATE ( > , 1 , 8 ) ) > 

142 


In  line  141,  PAGE:  and  DATE:  will  be  output  as  straight  text.  Do  not  confuse 
them  as  template  labels  as  they  are  not  between  curly  braces.  The  right  brace 
on  line  137  closed  off  the  previous  command  sequence.  Remember  that  any¬ 
thing  not  marked  as  a  comment  will  be  output  exactly  as  it  appears  to  the 
object  file.  Comments  begin  with  a  double  slash  (//). 


143 

144  APPLICATION  DOCUMENTATION  FOR  SYSTEM:  { F I LER00T ( Mdoc ) } . PRG 

145 

146  (IF  APPL_AUTHR  THEN) 

147  APPLICATION  AUTHOR:  <APPL_AUTHR> 

148  (ENOIF) 

149  (IF  APPL.CPYRT  THEN) 

150  COPYRIGHT  NOTICE..:  (APPL.CPYRT) 

151  (ENDIF) 

152  (IF  APPL.VERSN  THEN) 

153  DBASE  VERSION . :  (APPL.VERSN) 

154  (ENDIF) 

155 

156  // - 

157  //  START  PROCESSING  APPLICATION  OBJECT 

158  // - 

159  (IF  MENU  TYPE  =  App  THEN) 
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This  line  tests  the  selector  attribute  MENU-TYPE.  Note  that  the  double  equal 
sign  (  =  =  )  is  used  for  equality.  MENU-TYPE  can  hold  any  one  of  seven 
numbers,  depending  on  the  type  of  frame  that  was  designed  using  the  Appli¬ 
cations  Generator.  The  application  object,  for  instance,  would  generate  a  1, 
which  would  be  held  in  the  MENU— TYPE  selector.  App  was  given  the  value 
1  on  line  57. 

160 

161  DISPLAY  APPLICATION  SIGN-ON  BANNER:  (IF  0ISP_SIGN> YES{ELSE)NO(ENDI F) 

If  line  159  had  evaluated  as  true,  line  160  would  be  output  as  a  blank  line. 
When  the  Applications  Generator  interpreter  gets  to  line  161,  it  will  output 
the  text  DISPLAY  APPLICATION  SIGN-ON  BANNER:  exactly  as  it  is  writ¬ 
ten.  The  interpreter  only  operates  on  text  within  curly  braces. 

Line  161  examines  the  DISP- SIGN  selector.  If  it  is  true  (I,  or  any  number 
greater  than  0),  YES  is  output;  otherwise,  NO  will  be  output  to  the  file. 


of  the  selectors  in  the  INCLUDE  .def  files  for  the  correct  defaults. 


NOTE 

The  numeric  values  of  selectors  represent  the  answers  from  the  Appli¬ 
cations  Generator  screens,  so  YES  is  not  always  (1).  Check  the  values 


162  {Org_Appl=MENU_NAME+" . APP" ; 

163  IF  DISP.SIGN  THEN 

164  PRINT (Crl f ) ; 

165  ScrndumpO; 

166  ENDIF 

167  } 


ScrndumpO  is  a  user-defined  function.  At  the  end  of  this  program,  there  is 
an  INCLUDE  command  that  calls  Ds_ udf.cod.  This  file  contains  most  of  the 
user-defined  functions.  In  keeping  with  the  spirit  of  modular  programming, 
user-defined  functions  are  kept  in  a  separate  file. 

The  .app  extension  is  the  specific  extension  for  the  object  source  file  that 
the  template  interpreter  creates  to  hold  information  about  the  Application 
frame. 

Line  167  is  the  closing  brace  for  the  brace  that  begins  line  162.  Everything 
between  these  two  braces  will  be  operated  on  by  the  Applications  Generator 
interpreter. 
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168 

169 

170 

171 

172 

173 

174 

175 

176 

177 

178 

179 

180 
181 
182 

183 

184 

185 

186 

187 

188 


MAIN  MENU  TO  OPEN  (IF  DISP_SIGN  THEN > AFTER  S I GN-ON { END I F } :  (UPPER (MENU_MA I N > > 

(  EndofpageO;) 

SETS  FOR  APPLICATION: 


BELL  (IF  SET  BELDOFF { ELSE > ON  ( ENDI F> \ 

(  IF  SET_BELLFR  AND  SET_BELLDR  THEN) 

FREQUENCY  (SET  BELLFft)  DURATION  { SET_BELLDR> 

(ELSE  PRINT ( Crl f ) ;} 

(  ENDIF) 

CARRY  (IF  SET_CARRY)0N{ELSE)0FF{ ENDIF) 

CENTRY  (IF  SET_CENTRY )0N( ELSE)0FF(END I F> 

CONFIRM  (IF  SET_C0NFRM)0N( ELSE>0FF (ENDIF) 

DELIMITERS  (IF  SET_DELIM) ON  CHARACTER  (SET_DELCHR) (ELSE)OFF(ENDIF) 

DISPLAY  SIZE  (SCRN  SIZE)  LINES 
DRIVE  {UPPERtRUN  DRIVE)): 

ESCAPE  (IF  SET_ESCAPE)OFF{ELSE)ON{ ENDIF) 

PATH  (UPPER ( RUN_PATH ) ) 

SAFETY  (IF  SET_SAFETY}OFF(ELSE)ON( END  IF) 


189 

190 

191 

192 

193 

194 

195 

196 

197 

198 

199 

200 
201 


{  EndofpageO;) 

STARTING  COLORS  FOR  APPLICATION: 


//  CALL  UDF  Color! )  TO  GET  THE  ALL  THE  DIFFERENT  COLORS  FROM  THE  OBJECT 
COLOR  SETTINGS: 

STANDARD  COLOR  : 

(CoIor(CLR_STD  TXT) > , (Col or (CLR  ENH_TXT) ) 


TEXT 

HEADING 

BOX 

STATUS  LINE 
FIELDS 


(Color (CLR_TEXT) } 
(Color (CLR_HEADING) ) 
(Col  or (CLR_B0X ) } 
(Color  ( CLR_STATUS)  >’ 
(Col or (CLR  FIELDS)) 


{  EndofpageO;) 


The  user-defined  function  Color( )  has  the  value  of  the  particular  selector 
passed  to  it.  The  definition  for  the  Color()  function  includes  a  single  variable 
Getcolor,  which  will  get  the  selector  value.  The  selector  value  is  the  color 
setting  as  defined  in  dBASE  (for  example,  BG/N.GR+  /B).  The  Endofpage( ) 
user-defined  function  checks  the  number  of  lines  generated  so  far  to  see  if 
a  page  break  is  needed. 

User-defined  functions  are  created  with  the  DEFINE.. .ENDDEF  statement. 
Anything  defined  within  a  DEFINE  statement  is  local  to  the  statement. 

The  pending  value  when  ENDDEF/RETURN  is  reached  is  the  return  value. 
DEFINE  statements  may  not  be  nested.  See  the  Ds_udf.cod  file  for  examples. 
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202  {  IF  APPL  VIEW  THEN  //  IF  USER  FILLED  IN  APPLICATION  VIEW} 

203  DATABASE/ VIEW:  <APPL_VIEW> 

204  (  Endofpage( ) ;) 

205  (  EN0IF) 

206  (  IF  APPL.NDX  THEN) INDEX  FILE(S):  (APPL_NDX) 

207  {  EndofpageO;) 

208  {  ENDIF) 

209  {  IF  APPL_0RDER  THEN) INDEX  ORDER:  {APPL_0RDER> 

210  {  EndofpageO;} 

211  {  ENDIF} 

212 

213  (  PRINT ( REPLICATE ( "=" , 79 ) +Crl f) ; } 

214  {  NEWFRAME (MENU_MAIN ) ; } 


The  NEWFRAME( )  function  allows  a  change  to  a  different  object.  Before  the 
program  can  travel  the  menu  tree  of  an  application,  the  interpreter  must  be 
on  a  menu.  The  sign-on  object  is  unique  in  that  it  is  not  considered  a  menu. 
Therefore,  the  interpreter  must  be  positioned  at  the  main  menu  of  the  appli¬ 
cation  by  specifying  the  selector  MENU-MAIN. 


215  (ENDIF  //  IF  MENU  TYPE=  APP} 

216 

217  MENU/PICKLIST  DEFINITIONS  FOLLOW: 

218  (PRINT ( REPLICATE ( " , 33 ) -*-Crl  f ) ;} 


Lines  217  and  218  print  the  menu  header  and  underline  it. 


219  // - 

220  //  THIS  F0REACH  TREE  LOOP  WILL  START  A  MENU  TREE  WALK  OF  ALL  OBJECTS 

221  //  REFERENCED  BY  THE  APPLICATION.  THIS  IS  THE  MAIN  LOOP  OF  ANY  TEMPLATE 

222  //  THAT  PROCESSES  ALL  MENU  OBJECTS 

223  // - 

224  (F0REACH  TREE  Menu  } 


This  begins  the  FOREACH  TREE  loop,  which  is  closed  at  line  439  with  the 
NEXT  Menu  command.  FOREACH  TREE  causes  the  interpreter  to  travel 
through  all  the  frames  except  the  sign-on  frame. 


NOTE 

Menu  is  a  cursor  variable  that  holds  the  name  of  the  current  object 
type  specified  in  the  FOREACH  construct.  Cursor  variables  do  not 
have  to  be  declared  before  being  used.  Menu  is  in  lower  case  as  it  is 
an  arbitrary  name  chosen  by  the  programmer. 


The  frames  will  be  accessed  in  order  from  left  to  right,  one  level  at  a  time. 
For  example,  suppose  your  main  menu  A  called  two  other  menus,  B  and  C, 

B  called  D  and  E,  D  called  a  submenu  F,  and  C  called  a  submenu  G.  The 
interpreter  would  process  the  FOREACH  TREE  in  the  following  order:  A,  B, 
C,  D,  E,  G,  F.  This  processing  order  holds  true  unless  you  specifically  use  the 
NEWFRAMEO  function. 
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225  {  PAGEJECTO;  //  A  NEW  MENU  IS  NEXT) 

226  (  -n-Pagecnt; 


This  is  the  equivalent  of  Pagecnt  =  Pagecnt  +  1. 

227  PRINT ( Crl f  +  "PAGE:  "  +  STR(Pagecnt)  +  11  DATE:  "  + 

228  LTRIM<  SUBSTR ( DATE ( ) ,1,8))  +  Crl f+Crl  f) ; > 

229  {  Temp  Strng  =" LAYOUT  REPORT  FOR 

230  {  CASE  MENU_TYPE  OF) 

231  {  CASE  Popup :Temp_Strng  =  Temp_Strng  +  "POPUP  MENU:  ";) 

232  (  CASE  Bar:  Temp_Strng  =  Temp_Strng  +  "HORIZONTAL  BAR  MENU:  ";} 

233  {  CASE  Btch:  Temp_Strng  =  Temp_Strng  =  Temp_Strng  + 

234  "MULTIPLE  ACTION  SUMMARY  FOR  BATCH  OBJECT:";} 

235  (  ENDCASE) 

236  {  Temp_Strng  =  Temp_Strng  +  UPPER(MENU_NAME) ; 

237  PRINT(Temp_Strng+Crlf) ;} 

238  {  PRINT ( REPLICATE ( " , LEN(Temp_Strng) )+Crl f ) ; } 

239 


The  above  lines  of  code,  229  through  238,  set  up  and  print  the  line  LAYOUT 
REPORT  FOR  before  each  particular  menu  type,  and  then  underline  it  with 
hyphens.  Notice  that  the  syntax  of  the  CASE  statement  is  somewhat  different 
from  dBASE;  the  colon  is  part  of  the  syntax. 

MENU-TYPE  is  a  selector  that  holds  the  numeric  value  of  the  particular 
menu  being  worked  on  by  the  interpreter.  The  number  two  (2),  for  example, 
signifies  a  pop-up  menu.  The  Popup  constant  was  given  that  value  by  the 
ENUM  command  on  line  58. 


240  {  ScrndumpO;  //  A  USER  DEFINED  FUNCTION  TO  PRINT  AN  OBJECT  ON  THE  SCREEN) 

241 


ScrndumpO  is  a  user-defined  function.  Since  there  are  no  parameters  to  pass 
to  the  function,  the  braces  are  empty.  During  the  compile  process,  this  func¬ 
tion  will  have  been  included  from  the  Ds_ udf.cod  file  specified  at  the  end  of 
this  template. 

The  Applications  Generator  interpreter  will  act  on  Scmdump( )  and  print  out 
a  coordinate  matrix  of  the  screen  plus  the  contents  of  the  first  24  or  43  lines 
of  the  screen. 


1  242  {  EndofpageO ;) 

243  SETUP  FOR  (UPPER (MENU_NAME ) >  FOLLOWS: 

244  (PRINT (REPLICATE! "-" ,  LEN (MENU  NAME+"  FOLLOWS:")  +  10)+Crlf);} 
i  245 


In  line  244,  the  LEN  function  determines  the  number  of  hyphens  (-)  to 
use  as  an  underline.  This  number  is  made  up  of  the  length  of  the  string 
in  MENU-NAME  plus  the  length  of  the  string  "FOLLOWS:"  plus  10. 


246  {  LMARG ( 2 ) ; > 


LMARG(2)  indents  the  output  text  two  positions.  The  left  margin  will  remain 
fixed  at  this  position  until  changed  by  another  LMARG  command. 
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247  {  IF  MENU  OESC  THEN) 

248  DESCRIPTION:  (MENU_DESC> 

249  (  ENDIF) 


output  by  the  interpreter  at  that  point.  If  there  was  a  semicolon  after 
MENU—DESC .  the  contents  of  MENU—DESC  would  be  ignored  and 
nothing  would  be  sent  to  the  output  file. 


NOTE 

Line  248  does  not  have  a  semicolon  at  the  end  and  before  the 
curly  brace  so  that  the  value  of  the  MENU—DESC  selector  will  be 


250  (IF  MENU_PRMPT  THEN) 

251  MESSAGE  LINE  PROMPT  FOR  MENU:  (MENU_PRMPT> 

252  (ENDIF) 

253  // 

254  //  WE  USE  THE  INHERITANCE  PARADIGM  FOR  OPENING  OBF/VIEWS.  IF  THE  DBF/VIEW 

255  II  DOES  NOT  CHANGE  FROM  ONE  OBJECT  TO  ANOTHER  OR  FROM  ACTION 

TO  ACTION  WE  DON'T 

256  //  WANT  TO  KEEP  OPENING  THEM 

257  // 

258  (  IF  MENU  VIEW  AND  MENU  VIEW  !=  Global  View  THEN) 

259  //  IF  THERE  IS  DATA  IN  MENU  VIEW  AND  THAT  DATA  DOES  NOT  EQUAL  THE  GLOBAL  VIEW 

260  II  THE  DBASE  PROGRAM  WILL  OPEN  THE  NEW  DATABASE  261 

262  (  EndofpageO ;) 

263  DATABASE/ VIEW:  (MENU  VIEW) 

264  {  ENDIF) 

265  (IF  MENUJOX  AND  MENU_NDX  !=  Global_Ndx  THEN) 

266  (  EndofpageO;) 

267  INDEX  FILE(S) :  (MENU.NDX) 

268  (  ENDIF) 

269  (IF  MENU_0RDER  AND  MENUJDRDER  !«  Global _0rd  THEN) 

270  (  EndofpageO;) 

271  INDEX  ORDER:  (MENUJDRDER) 

272  (  ENDIF) 


Lines  258-272  document  the  database  files  and  index  files  used  by  the  appli¬ 
cation.  Lines  100-102  initialized  the  variables  from  the  application  objects. 
So,  if  the  database  or  index  file  has  not  changed,  there  is  no  need  to  print  a 
new  page  of  the  same  information. 
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273 

274 

(  LMARG ( 0 ) ;  > 

275 

{  EndofpageO;) 

276 

COLORS  FOR  MENU/PICKLIST: 

277 

278 

{  EndofpageO ;) 

279 

COLOR  SETTINGS: 

280 

STANDARD  COLOR 

(ColorICLR  STD  T)fT)>  ,(Color(CLR  ENH  TXT)  > 

281 

TEXT 

CCol or ( CLR  TEXT)) 

282 

HEADING 

(ColorlCLR  HEADING)) 

283 

BOX 

{ Col  or ( CLR  BOX)) 

284 

STATUS  LINE 

(ColortCLR  STATUS)) 

285 

FIELDS 

(Col or (CLR  FIELDS)) 

286 

287 

{  EndofpageO;) 

288 

(  //  SEE  IF  MENU  TYPE  IS  A  POPUP  OR  BAR  MENU 

289 

IF  MENU  TYPE  = 

Popup  OR  MENU  TYPE  =  Bar  THEN 

290 

Temp  Strng  = 

"HELP  DEFINED  FOR  MENU  VUPPER (MENU 

291 

Temp  Strng2 

REPLICATE ("— " ,LEN(MENU  NAME)+23); 

292 

293 

II  CALL  UDF  MENU  HLP  TO  PRINT  HELP  FOR  OBJECT 

294 

Menu  HI p (Temp  Strng,  Temp  Strng2); 

295 

Temp_Strng  = 

"BEFORE  MENU  DBASE  CODE  "+UPPER(MENU 

Menu_Hlp()  is  a  user-defined  function  held  in  the  programmer-created  file 
Ds_udf.Cod.  This  file  is  INCLUDEd  by  this  template  program  on  line  448. 
The  complete  function  is  shown  here  as  an  example  of  the  form;  normally 
it  does  not  appear  in  the  source  template. 

1 - 

{ 


DEFINE  menu_hlp(mhead, inline) ; 

II 

//  THIS  UDF  IS  USED  FOR  PROCESSING  MENU  LEVEL  HELP  TEXT 

// 

EndofpageO ; 

Print_Head*l ; 

FOREACH  MENU_HELP 
IF  MENU  HELP  THEN 
IF  Print.Head  THEN 
PRINT (crl f+mhead+cr  1 f+ml i ne+crl f ) ; 

LMARG ( 2 ) ; 

Print_Head=0; 

ENDIF 

PRINT (RTRIM(MENU_HELP)+crl f ) ; 
endofpageO ; 

ENDIF 


NEXT; 

endofpageO ; 
LMARG (0); 
RETURN; 
ENDDEF; 

) 
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Qnote 

The  form  is  DEFINE  function_name(arguments,  if  anv)...ENDDEF. 
The  argument  list  is  really  a  variable  declaration  local  to  the  function. 
The  variable  Print-Head  is  global  because  it  was  declared  in  the  main 
section  of  the  calling  template. 


296 

297  //  CALL  UDF  MENU.BEF  TO  PRINT  BEFORE  DBASE  CODE  FOR  OBJECT 

298  MENU_BEF(Temp_Strng,  Temp_Strng2) ; 

299  Temp’strng  =  "AFTER  MENU  DBASE  CODE  "+UPPER(MENU_NAME)+":"; 

300 

301  II  CALL  UDF  MENU.AFT  TO  PRINT  AFTER  DBASE  CODE  FOR  OBJECT 

302  MENU_AFT(Temp_Strng,  Temp_Strng2) ; 

303  PRINT (Crl f ) ;  i 

304  ENDIF 

305  > 

306  {  LMARG(O);  Temp  Strng  = 

307  IF  MENU_TYPE  =  Popup  OR  MENU_TYPE  =  Bar  THEN 

308  Temp_Strng  ="BAR  ACTIONS  FOR  MENU  "  +  UPPER (MENU_NAME)  +  "  FOLLOW:"; 

309  ENDIF 

310  IF  MENU_TYPE  =  F_Pick  OR  MENU_TYPE  =  S  Pick  OR  MENU  TYPE  —  V_Pick  THEN 

311  //  BELOW  IS  A  ANOTHER  WAY  TO  DO  THE  PREVIOUS  LINES  TEST 

312  //  IF  AT(ALLTRIM(STR(MENU_TYPE) ) ,"345")  THEN 

313  Temp_Strng  =  "PICKLIST  SPECIFICATION  FOR  "  +  UPPER(MENU  NAME)  +  "  FOLLOWS:"; 

314  ENDIF 

315  IF  MENU_TYPE  =  Btch  THEN 

316  Temp_Strng  ="BATCH  ACTIONS  FOR  MENU  "+UPPER(MENU_NAME)+"  FOLLOW:"; 

317  ENDIF 

318  IF  LEN(Temp_Strn j)  >  0  THEN 

319  PRINT(Temp_Strng  +  Crlf ) ; 

320  PRINT (REPLICATE! ,LEN(Temp_Strng))+Crlf) ; 

321  ENDIF 

322  } 

323  // 

324  (  IF  MENU  TYPE  =  F_Pick  THEN) 

325  FILES  PICKLIST 

326  - 

327  FILE  SPECIFICATION:  (UPPER(PICK_FILE) } 

328 

329  (  ENDIF) 

330  (  IF  MENU_TYPE  =  S_Pick  THEN) 

331  STRUCTURE  PICKLIST 

332  - 

333  FIELD  SPECIFICATION:  (UPPER(PICK  FIELD)) 

334 

335  (  ENDIF) 

336  (IF  MENUJYPE  =  V_Pick  THEN) 

337  VALUES  PICKLIST 

338  - 

339  FIELD  TO  LIST  VALUES  FOR:  (UPPER(PICK  VALUE)) 

340 

341  {  ENDIF) 

342  (  EndofpageO;) 


Lines  324-342  check  to  see  which  design  objects  were  used  at  this  level  of 
the  application  tree.  If  the  current  object  exists,  its  description  is  written  to 
the  output  file. 
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343  { 

344  Barcount  *  1; 

345  U - 

346  II  LOOP  THROUGH  EACH  BAR  IN  THE  MENU  -  EACH  BAR  IS  A  FIELD  IN  THE  GENERATOR 

347  // - 

348  FOREACH  FLD_ELEMENT  Fids  IN  Menu 

Line  348  is  the  start  of  the^  loop  that  goes  through  the  fields  defined  for  this 
design  frame  in  the  Applications  Generator.  FLD—ELEMENT  is  the  selector 
name  of  the  attribute  in  the  design  object.  Fids  is  the  cursor  variable  for  this 
FLD—ELEMENT  loop,  and  Menu  is  the  cursor  variable  for  the  outer  TREE 
loop. 


349  LMARG(l); 

350  IF  AT ( ALLTRIM (STR(MENU_TYPE) ) ,"279")  THEN  //  POPUP,  BAR  OR  BATCH  MENU 


Line  350  determines  the  MENU— TYPE  by  checking  if  the  contents  of 
MENU— TYPE  are  a  2,7,  or  9.  These  numbers  are  originally  specified  in 
the  INCLUDEd  Applctn.def  file  of  selector  definitions. 


351 

IF  MENU  TYPE  =  Btch  THEN  //  BATCH  OBJECT 

352 

Temp  Strng  =" BATCH  ACTION:  "  +  ALLTRIM(STR(Barcount) ) 

353 

ELSE 

354 

//  BAR  OR  POPUP  OBJECT 

355 

Temp  Strng  ="BAR:  "+ALLTRIM(STR(Barcount) ) 

356 

ENDIF 

357 

PRINTITemp  Strng  +  Crlf); 

358 

EN0IF 

359 

LMARG ( 2 ) ; 

360 

} 

361 

{  EndofpageO ;> 

362 

PROMPT:  (LTRIMIFLD  PICTUR) > 

363 

{  EndofpageO;) 

364 

//  NEXT  LINE  BOLDS  THE  WORD  ACTION 

365 

{  PRINT! "ACTION: "+CHR(13)+"  ACTION:"))  \ 

366 

{  CASE  MENU  ACT  OF) 

367 

{  CASE  Textno: )TEXT  ONLY  DEFINED  FOR  THIS  OPTION  - 

NO  ACTION 

368 

{  CASE  Open:) 

369 

//  FILETYPE  RETURNS  THE  EXTENSIONS  OF  THE  MENU 

370 

{  IF  AT(UPPER( FILETYPE (MENU  FILE)) ,"FIL,STR,VAL") 

THEN) 

371 

OPEN  A  PICKLIST  NAMED:  (OPEN  MENU) 

372 

{  ELSE) 

373 

OPEN  A  MENU  NAMED:  (OPEN  MENU) 

374 

{  ENDIF) 

375 

{  CASE  Brow:  INCLUDE  "DD  BROW. COD";) 

376 

{  CASE  Edit:  INCLUDE  "DD  EDIT. COD";) 

377 

{  CASE  Rept:  INCLUDE  "DD  REPT.C0D";) 

378 

{  CASE  Labi:  INCLUDE  "DD  LABL.C0D";) 

379 

{  CASE  Disp:  INCLUDE  "DD  LIST. COD";) 

380 

(  CASE  Appd:  INCLUDE  "DD  APND.C0D";) 

381 

{  CASE  Rcopy :  INCLU0E  "DD  COPY. COD";) 

382 

{  CASE  Repl :  INCLUDE  "DD  REPL.C0D";) 

383 

{  CASE  Dele:  INCLUDE  "0D  DELE. COD";) 

384 

{  CASE  Reca:  INCLUDE  "DD  RECL.C00";) 

385 

{  CASE  Pack:  INCLUDE  "DD  PACK. C00";) 

386 

{  CASE  I ndx : ) NEW  INDEX  FILE  (NDX  FILE) 

387 

INDEX  KEY: 
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388  (NDX_KEY>  \ 

389  {  IF  NDX  TAG) TAG  (NDX_TAG)  IN  (NDX  TAGINHENDIF)  \ 

390  {  IF  NDX_UN I QUE  THEN)  UN  I QUE { END  I  FT 

391  (  IF  NDX_DESCND>DESCENDING{ ENDI F> 

392  {  CASE  Rndx: >  RE  I NDEX  CURRENT  DBF: 

393  {  CASE  Sort:  INCLUDE  "DO  SORT. COD11;} 

394  {  CASE  Impt : INCLUDE  "DD_IMPT . COD" ; } 

395  (  CASE  Expt: INCLUDE  "DO  EXPT.COD";) 

396  {  CASE  Fcopy: INCLUDE  "DO  FCOPY.COD";) 

397  {  CASE  Dodb: } 


Lines  375-397  insert  the  appropriate  Template  Language  code  by  calling  it 
through  the  INCLUDE  command.  If  an  application  menu  used  the  BROWSE 
attribute,  all  the  possible  options  for  BROWSE  must  be  checked  and  docu¬ 
mented.  By  putting  these  sections  of  code  in  separate  files  to  be  INCLUDEd 
as  needed,  the  programmer  keeps  the  template  shorter  and  therefore  more 
readable.  It  also  allows  for  the  separate  maintenance  of  standard  formats. 


398  RUN  DBASE  PROGRAM:  DO  { PRG_F I LE> < I F  PRG_PARMS)  WITH  (PRG_PARMS  ENDI F> 


This  line  documents  which  dBASE  program  the  application  object  will  run. 


399  {  CASE  Indb: > 

400  INSERT  THE  FOLLOWING  DBASE  CODE: 

401  - 

402 

403  {  DbJnlinO;} 

404  {  CASE  Xdos : } 

405  RUN  DOS  PROGRAM  -  (DOS.FILEHIF  D0S.PARM}  (DOS  PARMMEN0IF} 

406  (  CASE  Call:) 

407  CALL  BINARY  PROGRAM  -  {BIN_FILE} .BIN  (IF  BIN_PARMS)WITH  (BIN  PARMSHENDIF) 

408  {  CASE  Retu: } RETURN  TO  CALLING  PROGRAM 

409  (  CASE  Quit:}QUIT  TO  DOS: 

410  {  CASE  Batch: }CALL  BATCH  NAMED:  C F I LEROOT ( UPPER ( BATCH_NAME ) ) > 

411  {  CASE  PI  mac :} PLAY  BACK  A  NPI  MACRO  (MACRO  NAME} 

412  (  ENDCASE) 

413  (IF  ITEM_PRMPT  THEN} 

414  MESSAGE  LINE  PROMPT  FOR  ITEM:  (ITEM  PRMPT) 

415  (ENDIF) 

416  // 

417  //  SEE  IF  MENU  LEVEL  AND  ITEM  LEVEL  DBF/VIEW  ARE  DIFFERENT 

418  (  IF  ITEMJIEW  AND  ITEMJIEW  !=  MENU_V I EW1NEW  DATABASE/ VIEW:  (ITEMJIEW) 

419  (  EndofpageO ;} 

420  (  ENDIF) 

421  (  IF  ITEMJDX  AND  ITEM_NDX  !=  MENU_NDX)NEW  INDEX  FILE(S):  (ITEM_NDX) 

422  (  EndofpageO;} 

423  (  ENDIF} 

424  {  IF  ITEM_0RDER  AND  ITEMJ3RDER  !=  MENU_0RDER) NEW  INDEX 

ORDER:  (ITEMJJRDER) 

425  (  EndofpageO;) 

426  (  ENDIF) 

427  // - 

428  //  NEXT  FOUR  FUNCTIONS  ARE  USER  DEFINED  SEE  DS_UDF . COD 

429  // - 

430  (  EndofpageO;  //  CHECK  FOR  END  OF  PAGE) 

431  (  Item  HlpO ;  //  PRINT  HELP  TEXT) 

432  {  Item_Bef() ;  //  PRINT  BEFORE  DBASE  CODE) 
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433  {  Item_Aft();  //  PRINT  AFTER  DBASE  CODE) 

434  {  LMARG(O) ;> 

435  (  PRINT ( REPLICATE ( , 80 ) +Cr 1 f+Crlf) ;) 

436  {  Barcount  =  Barcount  +  I;) 

437  {  Endofpage( ) ;) 

438  (  NEXT  Fids;  //  END  OF  FOREACH  FLD  ELEMENT) 

439  (NEXT  Menu  //  ENO  OF  FORTREE  LOOP) 


If  there  is  another  object  in  the  tree  structure,  the  NEXT  Menu  command  of 
line  439  will  cause  that  object  to  be  loaded  and  any  actions  to  be  performed. 
All  the  commands  of  a  batch  menu  object,  for  example,  will  be  processed 
through  the  FOREACH  loop. 


An  explicit  0  is  RETURNed  on  line  444,  otherwise  the  dBASE  interpreter 
will  think  that  an  error  occurred.  The  template  interpreter  RETURNS  a  num¬ 
ber  other  than  0  if  template  generation  is  prematurely  terminated.  This  num¬ 
ber  may  be  a  DOS  error  level  message  or  an  internal  dBASE  error  message 
number. 


445  // 

446  //  - 

447  //  USER  DEFINED  FUNCTIONS  FOLLOW 

448  II  - 

449  // 

450  (  INCLUDE  "DSJJDF.COD";) 

451  II  EOP  DS_D0C . COD 


This  ends  the  walkthrough  of  the  sample  template. 


440 

441 

442 

443 

444 


END  OF  APPLICATION  DOCUMENTATION 
II  JUMP  LABEL  FOR  NO  GENERATION 
{ Nogen :) 

{RETURN  0;) 


■ 
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Building  Blocks 


The  Source  Template 

A  source  template  is  an  ASCII  file  comprised  mostly  of  text  and  various  seg¬ 
ments  of  template  language  code.  For  example, 


This  menu  is  named  (MENU  NAME). 

Bar  1  of  Menu  (MENU_NAME>  is  {FLO.PICTUR}. 


In  this  example,  {MENU_NAME}  and  {FLD—PICTUR}  are  part  of  the  template 
programming  language  and  will  be  expanded  by  the  design  object  interpreter: 
for  example,  the  Applications  Generator.  The  text  before  and  after  will  be 
copied  directly  to  the  output  file. 

The  source  template  has,  by  convention,  the  file  extension  .cod.  This  file 
must  be  compiled  by  the  template  compiler  Dtc.exe  before  it  can  be  used. 
Dtc.exe  will  create  a  compiled  template  with  the  specified  extension.  The 
conventional  extension  is  .gen.  The  template  .gen  file  is  used  by  the  Applica¬ 
tions  Generator,  or  the  reports,  forms,  and  labels  generators  with  their  spe¬ 
cific  design  files,  to  produce  the  final  ASCII  output  file.  This  final  output  file 
may  be  a  dBASE  program  with  the  extension  .prg. 

Certain  object  designers  expect  compiled  templates  under  specific  names. 
These  are  described  in  Table  3-1.  This  table  also  includes  the  DOS  environ¬ 
ment  variable  used  to  change  the  template  name. 


Table  3-1  Types  of  design  objects 


Object 

Template  Name 

DOS  Environment  Nfariable 

Forms 

Form. gen 

SET  DTI _ FORM  =  <  filename  > 

Reports 

Report.gen 

SET  DTI _ REPORT  =  <  filename  > 

Labels 

Label. gen 

SET  DTI _ LAB  Ell  =  <  filename  > 

Quick  Application 

Quickapp.gen 

None  —  use  Generate  menu 
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NOTE 

If  you  write  a  new  template  for  any  of  the  above  files,  be  sure  to  save 
the  original  under  another  name.  These  design  screen  generators 
expect  templates  with  these  specific  names  unless  you  set  the  DOS 
environment  variable  to  override  the  default  filename  (for  example, 
DTI..  FORM  =  Myform.gen). 


Applications  Generator  object  files,  other  than  Quick  App,  only  require  the 
.gen  extension.  The  default  name  for  an  application  if  one  is  not  specified  is 
Menu. gen. 


Source  Template  Components 

A  template  is  made  up  of  four  components: 

■  Comments 

■  Introduction 

■  Text 

■  Commands 

Comments 

You  should  use  comments  to  explain  segments  of  code  to  ensure  later  read¬ 
ability  for  yourself  or  others.  Comments  are  text  to  the  right  of  the  marker  // 
(slash-slash).  They  must  start  in  column  1  if  they  are  outside  curly  braces. 
Inside  curly  braces,  the  comment  may  start  in  any  column.  Comments  may 
not  appear  within  quotation  marks  (").  Multiple  lines  of  comments  require  a 
//  at  the  beginning  of  each  comment  line.  Comments  are  omitted  during  the 
compile  process. 


Introduction 

Introductory  text  identifies  a  particular  compiled  template.  The  Introduction 
is  text  appearing  before  the  first  left  brace  ({)  that  is  not  set  off  as  a  comment. 
(The  first  left  brace  marks  the  beginning  of  the  first  template  program  com¬ 
mand.)  Introductions  may  be  up  to  4K  in  size.  You  can  view  them  by  using 
the  DOS  TYPE  command  on  a  compiled  file.  Introduction  text  is  not  copied 
to  the  output  file. 


Text 


This  is  material  that  you  wish  to  pass  unchanged  by  the  compiler  and  gener¬ 
ator  to  the  final  output  file.  Text  is  any  data  outside  of  comments  or  braced 
command  segments  after  the  first  left  brace.  It  is  copied  directly  to  the  out¬ 
put  file  without  being  changed.  Text  can  be  standard  program  routines,  or 
descriptions  used  repeatedly. 
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Commands 

Commands  tell  the  compiler  what  to  do  with  the  information  held  in  the 
design  files,  or  with  information  supplied  within  the  braces.  They  are  found 
between  left  and  right  curly  braces  and  outside  of  comments.  Thev  mav  be 
more  than  one  line  long.  A  hard  carriage  return  inside  braces  is  ignored, 
since  anything  inside  braces  is  considered  a  command.  Comments  may  be 
inside  braces  as  long  afe  they  begin  with  the  //  marker.  White  space  has  no 
meaning  within  braces  other  than  to  delimit  symbols  of  the  template  language. 


Keywords 

Keywords  are  reserved  words  in  the  language.  They  may  be  part  of  a  com¬ 
mand  or  they  may  be  associated  with  the  design  object  file  structure.  In  par¬ 
ticular,  all  commands,  selectors,  and  functions  are  keywords. 


NOTE 

Please  review  the  .def  files  provided  with  the  product  for  specific 
information  regarding  selectors  and  keywords  for  dBASE  IV  internal 
settings. 


Selectors 


Selectors  are  template  language  data  names.  There  are  four  classes  of 
selectors: 

■  Elements  that  make  up  the  design  object  file  (for  example, 
BOX-ELEMENT) 

■  Attributes  of  an  element  (for  example,  ROW—POSITN) 

■  Functions  (for  example,  DATEQ) 

■  Miscellaneous  names  (for  example,  TREE,  DOSFILE) 

A  selector  is  a  symbol  mapped  internally  to  a  unique  identification  number. 
This  number  cannot  be  modified.  The  symbol  is  the  selector  name  and  the 
number  is  called  its  IID  (item  identification). 

The  syntax  for  declaring  a  selector  is: 

_l - 

i  (SELECTOR  <symbol>  <number>  [,<symbol>  <number>] . . . 

You  must  declare  all  selectors  referenced  in  a  template  before  using  them. 
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There  are  five  standard  selector  files  provided  with  the  language.  These  are: 

■  Report. def  for  reports 

■  Form. def  for  forms 

■  Label. def  for  labels 

■  Applctn.def  for  Applications  Generator  objects 

■  Builtin.def  for  built-in  functions  and  other  miscellaneous  declarations 

You  declare  these  standard  selector  definitions  in  a  template  by  using  the 
INCLUDE  command  with  the  desired  filename.  Most  templates  include 
Builtin.def.  Templates  that  deal  with  Applications  Generator  design  files 
include  Applctn.def.  Templates  that  deal  with  reports,  forms,  and  labels 
design  files  include  their  particular  .def  file. 


selector  number  for  different  symbols. 

Using  the  selector  within  a  template  returns  some  information  about  the 
item  referenced.  Most  selectors  return  strings  or  constants  when  used. 
These  results  can  be  printed.  If  you  want  to  get  the  IID  for  a  particular 
selector  instead  of  a  value,  preface  the  name  with  the  @  symbol. 


The  selector  name  is:  Menu_Name 

The  identification  number  is:  { @MENU_NAME> 

The  value  returned  is:  {MENU_NAME> 


The  IIDC()  function  also  returns  the  identification  number. 


NOTE 

You  cannot  include  Applctn.def  in  the  same  template  with  Report.def. 
Form. def,  or  Label. def.  These  two  sets  of  .def  files  declare  the  same 


Variables 


Three  types  of  variables  are  supported.  They  are: 

■  Numbers  (signed  long  integers) 

■  Strings  (up  to  237  characters,  may  include  graphic  characters) 

■  Cursors 
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Number  and  String  Variables 

Number  and  string  variables  are  declared  using  the  VAR  command.  Thev 
have  no  inherent  type  and  may  change  type  several  times  as  the  result  of 
assignments  in  the  template. 


Cursor  Variables 


Cursor  variables  are  usually  declared  as  part  of  the  FOREACH  loop  command. 
They  hold  the  current  processing  position  for  the  interpreter  within  the  TREE 
structure  of  the  application,  the  repeated  occurrences  of  an  element,  or  the 
repeated  occurrences  of  an  attribute. 

The  MAKEC()  function  explicitly  creates  a  cursor  variable  from  the  named 
selector.  Although  it  is  part  of  the  internal  implementation  of  the  FOREACH 
...NEXT  command,  you  can  also  use  it  in  a  program. 

When  a  selector  is  referenced,  all  the  items  pointed  to  by  active  cursors  are 
searched.  The  search  starts  with  the  inner  nested  cursor  first  and  proceeds 
outward  until  the  selector  value  is  located.  If  nothing  has  been  found  at  the 
outermost  cursor  level,  the  frame  attributes  are  searched. 

You  can  override  this  search  sequence  by  giving  an  explicit  cursor  reference 
to  the  selector.  Preface  the  selector  name  with  the  cursor  name  followed  by 
a  dot.  The  syntax  is  <  cursor  >  .  <  selector  >  . 


(FOREACH  ELEMENT  k  > 

{  FOREACH  FLD  ELEMENT  m  > 

The  row  of  k  is  Ck . R0W_P0SITN> 

WOverride  the  current  cursor 

Wreference  of  cursor  variable  m 

The  row  of  m  is  (m.R0W_P0SITN}  which  is  the  same  as 

the  unqualified  {R0W_P0SITN> . 

(  NEXT  m; } 

(NEXT  k;l 


NOTE 

Please  review  the  .def  files  that  come  with  the  product  for  a  break¬ 
down  of  selectors  by  specific  FOREACH  <  loop  selector  >  . 
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Special  Characters 


Table  3-2  lists  and  explains  the  special  characters  used  in  a  template  file. 

Table  3-2  Special  template  characters 

Character 

Description 

{}  braces  segment 

Anywhere  outside  of  comments  delimits  a  command. 
The  material  within  the  brace  must  therefore  be  a 
Template  Language  expression. 

\  backslash 

At  the  end  of  the  line,  removes  the  carriage  return. 

At  any  place  but  the  end  of  the  line,  causes  any  spe¬ 
cial  meaning  of  the  next  single  character  to  be 
ignored. 

;  semicolon 

Separates  statements  within  braces.  If  it  is  between 
the  end  of  an  expression  and  the  right  brace,  the  cur¬ 
rent  value  of  the  expression  is  not  output. 

()  parentheses 

Encloses  function  arguments  and  nested  expressions 
within  braces. 

//  slash-slash 

At  the  beginning  of  the  line,  or  anywhere  within 
curly  braces  and  not  in  double  quotes,  indicates 
a  comment. 

Blank 

Before  {commands}  causes  a  new  line.  A  blank  line 
in  a  template,  outside  of  braces,  causes  an  explicit 
blank  line  in  the  resulting  object  file. 

"  double  quotes 

Reserved  for  use  as  string  delimiters  and  as  code 
embeds  for  menu  and  list  objects.  Not  allowed  in 
the  layout  of  screen  objects  (forms,  reports,  labels, 
menus,  application  objects)  or  in  the  help  text  or 
message  line  prompts  for  menu  and  list  obects. 

Command  Syntax 

The  command  syntax  within  a  template  is: 

[operator]  <  expression  >  [[operator]  [(expression)]...] 
For  example: 


(a=5;b=*(a+b)  *  c; 

IF  FUNCl(x)  &&  FUNC2("abc")  THEN 
PRINT(x) 

ELSE 

PRINT(y) 

ENDIF) 
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mm  note 

In  the  Template  Language,  &&  means  logical  and,  not  a  dBASE 
comment. 


Simple  Expressions 


The  Template  Language  supports  expressions  that  cannot  be  broken  down 
into  smaller  components.  These  are: 


Variable  name 

Constant  (see  Enum  Operand) 
Selector 

User-defined  function  call 
Built-in  function 
CASE  ...ENDCASE 
IF...THEN...ENDIF 


Complex  Expressions 


You  can  develop  more  complex  expressions  with  unary  and  binary  operators. 
The  operators  perform  type  conversions  automatically. 


Expression  Result 

When  a  simple  or  complex  expression  evaluation  reaches  the  right  brace  (}) 
that  indicates  the  end  of  a  command,  the  current  value  of  the  expression  is 
printed  to  the  output  file.  If  there  is  a  semicolon  between  the  end  of  the 
expression  and  the  right  brace,  the  current  value  is  not  printed. 


Operands 

The  operands  for  the  language  are: 

■  Constants  —  Letters  and  numbers.  For  example,  5,11,  "Joe" ,  are  all  valid. 
Only  double  quotes  are  valid  string  delimiters.  Constants  may  also  be 
declared  symbolically  with  the  ENUM  statement. 

■  ENUM  textno  =  0,  open,  brow,  ... 

textno,  open,  and  brow  in  this  example  are  enumerated  constants  with 
the  order  value  of  0  for  textno,  1  for  open  and  2  for  brow.  When  the 
template  is  compiled,  these  variable  names  will  be  replaced  by  the 
number  that  represents  their  order  in  the  list. 
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■  Variables  —  You  can  use  memory,  cursor,  and  enumerated  variables. 

■  {VAR  a,b.page_count;}  —  In  this  example,  a,  b.  and  page— count  are 
memory  variables  with  values  you  can  change. 

■  {FOREACH  TREE  w  ...COMMANDS...  NEXT  w;} 

w  is  a  cursor  variable  and  acts  as  a  position  pointer.  You  cannot  use 
the  assignment  operator  to  assign  a  value  to  it  since  it  is  just  a  place 
marker  for  the  interpreter. 

■  Selectors  —  These  are  the  template  data  label  names.  They  return  infor¬ 
mation  to  you  about  the  elements  and  their  attributes.  You  cannot  assign 
information  to  a  selector.  That  is  done  when  you  design  or  revise  the 
object. 

■  Functions  —  These  include  the  values  returned  by  pre-defined  func¬ 
tions  included  from  Builtin.def,  and  Template  Language  user-defined 
functions. 


Operators 

Operators  work  on  the  terms  of  an  expression.  They  are  described  below. 


Types 


The  Template  Langu  age  uses  assignment,  unary,  and  binary  operators  that 
can  produce  numeric,  cursor,  or  string  results.  Logical  or  relational  results 
are  returned  as  numeric  1  for  true  or  numeric  0  for  false. 

Logical  results  obey  the  following  rules: 

■  To  be  logically  true,  a  value  must  be  either  numeric  and  non-zero,  or  a 
string  and  not  null  ("")■ 

■  To  be  logically  false,  a  value  must  be  either  numeric  with  a  value  of  0, 
or  a  null  string.  A  null  string  signals  that  the  value  does  not  exist  in  the 
design  file. 


Assignment 

An  assignment  operator  simultaneously  creates  a  new  value  and  stores  it  in 
a  variable.  This  new  value  will  then  be  output  by  the  template  if  not  further 
adjusted.  These  operators  are  listed  in  Table  3-3. 
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Table  3-3  Assignment  operators 


Operator  Description 

=  equals 

+  =  a  +  =  /  is  the  same  as  a  =  a  +  1 

~  =  a  —  =  1  is  the  same  a s  a  =  a  —  1 

+  +  numeric  add  one,  same  as  +  =  / 

(  +  +  a  is  the  same  as  a  +  =  1  which  is  the  same  a s  a  =  a  +  1) 
numeric  minus  one,  same  as  —  =  1 

(  —  a  is  the  same  a s  a  =  a  —  1  which  is  the  same  as  a  —  =  /) 


NOTE 

The  +  +  and - assignment  operators  cannot  be  used  with  string 

variables.  +  +  <  string  >  makes  no  sense. 


Unary 

A  unary  operator  is  placed  in  front  of  an  operand  and  works  on  that  operand 
only.  These  operators  are  listed  in  Table  3-4. 


Table  3-4  Unary  operators 


Operator 

Description 

+ 

numeric  positive 

numeric  negative 

j 

numeric  logical  not 

not 

null  =  1,  non-null  =  0 

(  ) 

parentheses  for  grouping 

@ 

yield  the  integer  value  for  the  selector 

NOTE 

The  @  operator  must  be  followed  by  a  selector.  It  gives  the  integer  IID 
value  defined  for  that  selector,  so  that  a  selector  may  be  passed  to  a 
function  as  a  selector.  If  the  @  is  not  used,  the  value  of  the  selector 
will  be  passed. 


Binary 

Binary  operators  are  placed  between  strings,  numbers,  or  logical  expres¬ 
sions.  They  yield  a  result  based  on  the  operands  on  either  side  of  the  opera¬ 
tor.  Table  3-5  lists  these  operators. 
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Table  3-5  Binary  operators 


Operator 


/ 

% 

& 

I 


< 

<  = 

>  = 

> 

&& 

II 

and 

or 


Description 

numeric  addition,  string  concatenation 

numeric  subtraction 

numeric  multiplication 

numeric  division 

numeric  modulo 

bitwise  numeric  and 

bitwise  numeric  or 

bitwise  numeric  xor;  (a  or  b)  and  not  (a  and  b) 

numeric  or  string  less  than 

numeric  or  string  less  than  or  equal 

numeric  or  string  compare 

numeric  or  string  not  equal 

numeric  or  string  greater  than  or  equal 

numeric  or  string  greater  than 

logical  and 

logical  or 

logical  and 

logical  or 

dot  operator 


NOTE 

The  dot  operator  treats  the  expression  on  the  left  as  a  cursor  and  the 
expression  on  the  right  as  a  selector  or  integer.  This  means  that  the 
value  of  the  attribute  of  the  indicated  selector  or  integer  is  fetched. 


Bitwise  Logical 

Three  bitwise  binary  operators  for  numbers  are  supported. 

I  inclusive  OR 
&  inclusive  AND 
exclusive  OR  (XOR) 

The  1  ’s  complement  unary  operator  ~  is  supported. 
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These  operators  convert  the  type  of  their  operands  to  numbers  and  perform 
32-bit  operations.  These  operators  allow  you  to  manipulate  number  variables 
directly  within  the  Template  Uanguage.  An  example  of  this  would  be  the  val¬ 
ues  stored  for  the  corresponding  dBASE  colors. 


Shift 


Number  variables  are  stored  internally  as  32-bit  integers.  Numbers  therefore 
may  be  shifted. 

<  <  <  n  >  Shift  left,  throw  away  leading  bits,  add  trailing  zeroes. 

>  >  <  n  >  Shift  right,  throw  away  trailing  bits,  add  leading  zeroes. 


Precedence 

Operators  have  precedence  rules  that  determine  the  order  of  operations. 
Assignment  operators  are  directly  connected  to  the  symbol  on  the  left,  so 
assignment  operators  on  the  right  have  lower  precedence. 

Example: 

z  =  a  +  b*cld  +  e 

In  this  statement,  the  multiplication  will  be  evaluated  first,  followed  by  the 
addition,  and  then  the  bitwise  or. 

All  operators  are  evaluated  in  the  following  order: 

.  (dot  operator) 

!,  not,  ~,  @,  —  (unary) 

\  /.  % 

+  ,  - 
<  <,  >  > 

<  .  <  =,  >,  >  = 


& 

I,  “ 

and,  && 
or,  1 1 


All  operations  at  the  same  precedence  level  are  carried  out  in  order  from 
left  to  right.  You  can  use  parentheses  to  change  the  precedence.  Operations 
within  the  inner  nested  parentheses  are  performed  first. 
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Functions 

4.  Commands 

5.  Functions 


JOBN'AME:  No  Job  Name  PAGE:  2  SESS:  4  OUTPUT:  Fri  Aug  5  00:02:34  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpsecdiv2 


JOBNAME:  No  Job  Name  PAGE:  1  SESS:  8  OUTPUT:  Fri  Jul  29  20:27:54  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpchap4 


Commands 

This  chapter  describes  the  commands  used  in  the  Template  Language. 


Symbols  and  Conventions 

The  symbols  and  conventions  used  for  writing  the  command  syntax  of  the 
Template  Language  reflect  common  usage. 


Table  4-1  Symbols  and  conventions 


Symbol  Use 

<  >  Angle  brackets  indicate  you  must  enter  the  enclosed  item. 

Do  not  type  the  angle  brackets. 

[  ]  Square  brackets  indicate  that  the  enclosed  item  is  optional. 

Do  not  type  the  square  brackets. 


Limitations 

The  limitations  on  naming  files  are  the  same  as  in  DOS.  Filenames  may  be 
up  to  eight  characters  long.  They  must  begin  with  a  letter  and  cannot  con¬ 
tain  embedded  blank  spaces.  Letters,  numbers,  and  underscore  characters 
are  permitted. 
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As  in  DOS,  file  extensions  of  up  to  three  characters  using  letters  and  num¬ 
bers  are  permitted.  The  extensions  listed  in  Table  4-2  are  reserved. 


Table  4-2  Reserved  file  extensions 


Extension 

File  type 

.app 

Application  object 

.bar 

Bar  menu 

•pop 

Pop-up  menu 

.str 

Structure 

.fil 

Files 

.val 

Values 

.bch 

Batch 

.scr 

Screen 

.lbl 

Label 

.frm 

Report 

.npi 

Source  for  Dgen.exe 

NOTE 

Read  Chapter  6,  “Creating  Templates  —  The  Template  Language  Inter¬ 
preter,"  for  more  information  on  .npi  files. 


Compiler  Commands 

These  commands  allow  you  to  activate  certain  options  during  compilation. 


Table  4-3  Compiler  commands 


Command 

Description 

INCLUDE 

Include  information  from  named  file 

#CODON 

Include  assembler  statements  in  compiler  listing 

#CODOFF 

Omit  assembler  statements  from  compiler  listing.  This  is 
the  default. 

#LSTON 

Turns  list  output  on  if  -1  was  used  in  the  command  line 
when  invoking  the  compiler.  This  is  the  default. 

#LSTOFF 

If  list  output  is  on,  turns  it  off 
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NOTE 

Read  Chapter  6,  "Creating  Templates  —  The  Template  Language  Com¬ 
piler,"  for  more  information. 


Definition  Commands 

The  commands  described  below  define  variables  and  user-defined  functions. 


DEFINE 


This  command  declares  a  user-defined  function  for  use  within  the  Template 
Language  only. 


Command  Syntax 

DEFINE  <  funcname  >  ([  <  vamame  >  ]  [,  <  vamame  >  ...])...RETURN 
ENDDEF 

Rules 

User-defined  functions  must  begin  with  DEFINE  and  end  with  ENDDEF. 
DEFINE  statements  may  not  be  nested  within  other  DEFINE  statements. 
Anything  declared  within  a  DEFINE  statement  is  local  to  that  statement. 

If  there  is  a  pending  value  when  RETURN/ENDDEF  is  reached,  that  pending 
value  is  the  return  value. 


Example 


(DEFINE  endofpageO ; 

VAR  length; 
length  -  CURLINEO; 

IF  length  >  60  THEN 
pagecnt+*I; 

PAGEBREAKO; 

PRINKCRLF+"  Page  "+STR(pagecnt) ) ; 
ENDIF 
RETURN; 

ENDDEF;} 
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ENUM 


This  command  substitutes  a  number  or  string  constant  value  for  a  symbolic 
name  at  compile  time.  This  helps  make  a  program  more  readable  by  assign¬ 
ing  values  to  all  the  symbol  names  listed.  If  integers  are  specified,  the  default 
values  are  the  integer  values  in  order  following  the  first  or  subsequent 
assignments. 

Command  Syntax 

ENUM  <  symbol  name  >  =  <  exp  >  [,  <  symbol  name  > 

[=  <  exp  >]...] 

Rules 

After  the  first  numeric  assignment  to  a  symbolic  name,  the  subsequent  sym¬ 
bols  get  assigned  sequential  values.  A  new  assignment  restarts  the  sequence. 

Spaces  may  be  used  instead  of  commas. 

Sequential  values  are  0-n,  A-Z. 

The  entire  ASCII  standard  set  is  available.  Values  higher  than  255  will  not  be 
output. 


NOTE 

ENUM  creates  a  list  of  constants  assigned  by  the  compiler.  You  cannot 
change  the  value  assigned  to  the  constant  when  running  the  compiled 
template. 


Example 


(ENUM  menu  =  1, 
dialog, 
keyword, 
new_start  =  6, 
more;} 


This  will  result  in  the  assignment  of  1  to  menu,  2  to  dialog,  3  to  keyword, 
6  to  new_start,  and  7  to  more. 


VAR 


This  command  declares  variable  names  for  later  use  within  a  template. 

Command  Syntax 

VAR  <  vamame  >  [,  <  vamame  >  ]... 
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Rules 

<  vamame  >  must  begin  with  a  letter  or  underscore.  Successive  characters 
may  be  letters,  underscores,  or  digits. 

A  variable  name  may  be  up  to  200  characters  long. 

Variables  declared  within  a  DEFINE  statement  are  local  to  that  statement 
Variables  declared  outside  a  DEFINE  statement  are  global  to  the  template. 
Local  variables  take  precedence  over  global  ones. 

Example 

(VAR  x,y,menu_one,teinporary_count;> 


Program  Flow  Commands 

CASE...ENDCASE 

This  command  selects  one  course  of  action  from  a  set  of  alternatives. 

Command  Syntax 

CASE  <  exp  >  OF  [CASE]  <  n:  >  <  commands  >  [...OTHERWISE] 

...  ENDCASE 


Rules 

CASE  selectors  (n:)  must  be  numeric  unless  the  ENUM  command  is  used 
prior  to  the  CASE  statement. 

Example 


(CASE  MENUACT  OF 
1:  GOTO  nogen 
2:)Today  is  (DATED) 
(3:  INCLUDE  "test.doc" 
ENDCASE} 


GOTO 


This  command  jumps  the  flow  of  control  to  the  specified,  labeled  statement. 

Command  Syntax 

GOTO  <  label  > 

Rules 

The  specified  label  name  follows  the  same  rules  as  a  VAR  name. 
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The  label  name  should  appear  on  a  command  line  by  itself  and  must  have  a 
colon  (:)  as  its  last  character. 

Example 


{scrntop:) 

(IF  count  >  20  THEN  GOTO  scrnbot  ENDIF 
line  =  SCREEN ( count ) ; 

IF  count  <10  THEN 

linecnt  =  "0"+STR(count) ; 

ELSE 

linecnt  =STR( count); 

ENDIF 

PRINT ( 1 i necnt+" : "+1 i ne+CRLF) ; 

count=+l 

GOTO  scrntop;) 

(scrnbot:) 

(RETURN;) 


IF.. .THEN.. .ENDIF 


This  command  tests  for  a  true/false  condition  and  executes  separate  com¬ 
mands  depending  on  the  result. 

Command  Syntax 

IF  <  condition  >  [THEN]  <  commands  >  [ELSE  <  commands  >  ]  ENDIF 

Rules 

Nesting  rules  are  the  same  as  for  the  dBASE  IF... ENDIF  command. 

In  cases  where  the  meaning  is  unambiguous,  the  IF  statement  may  be  abbre¬ 
viated,  as  in  the  second  example. 

Example 


(IF  a  <  b  THEN  x  =  25;) 

text  for  a  *  (a)  and  x  =  (x) 

(ELSE  x  =  15;) 

text  for  b  =  (b)  and  x  =  (x) 

(ENDIF) 

(IF  "pigs"  !=  "aviators"  GOTO  obviously) 
Learn  something  new  every  day. 
(obviously: )Pigs  can't  fly 
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RETURN 

Inside  user-defined  functions,  RETURN  exits  to  the  caller  and  provides  the 
pending  value.  Outside  a  function,  it  terminates  a  template  run. 


Command  Syntax 

RETURN  [  <  exp  >  ] 

Rules 


This  command  is  optional  inside  functions.  If  it  is  not  provided,  the  RETURN 
value  will  be  the  pending  value,  if  any,  provided  by  the  function. 

When  used  outside  functions,  RETURN  terminates  the  template  run.  If  the 
run  terminates  with  a  RETURN  value  other  than  0,  it  indicates  an  error  con¬ 
dition.  This  means  you  must  specify  RETURN  0  at  the  end  of  your  template. 


NOTE 

Non-zero  RETURN  error  messages  will  be  displayed  if  you  are  generat¬ 
ing  files  from  within  dBASE.  If  you  are  using  the  stand-alone  inter¬ 
preter,  run  dGEN  within  a  batch  file  and  check  the  DOS  ERROR- 
LEVEL  number. 


Example 


(DEFINE  sqr(x) 
RETURN  x*x; 
ENDDEF) 


Loop  Commands 

FOREACH...NEXT 

This  command  allows  you  to  move  sequentially  through  repeated  occur¬ 
rences  of  DOS  files,  design  object  files,  elements,  and  attributes. 

Command  Syntax 

FOREACH  <  loop  selector  >  [  <  cursor  var  >  ]  [IN  <  cursor  var  >  ]  ...NEXT 

Rules 

Each  construct  declares  a  cursor  variable  that  moves  through  some  repeated 
data  until  it  reaches  the  end  of  the  data. 

The  FOREACH  loop  syntax  always  ends  with  the  NEXT  [  <  cursor  var  >  ] 
command. 
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The  loop  selectors  can  be  found  in  the  following  .def  files: 

■  Applctn.def 

■  Loop  selectors  for  all  object  files 

ELEMENT 
BOX_ELEMENT 
FLD_ ELEMENT 
TEXT-ELEMENT 
TREE 

■  Specific  Loop  Selectors  for  .app  files. 

Frame  Selector: 

TEXT-ITEM 

■  Specific  Loop  Selectors  for  .pop,  .fil,  .str,  .val,  .bar,  .bch  files 
Frame  Selectors: 

MENU-HELP 

MENU_BEFORE 

MENU_AFTER 

Field  Selectors: 

INLINE-DO 

ITEM-HELP 

ITEM_BEFORE 

ITEM_AFTER 

■  Form. def 

■  Loop  Selectors 

ELEMENT 
BOX-ELEMENT 
FLD— ELEMENT 
TEXT-ELEMENT 

■  Label.def 

■  Loop  Selectors 

ELEMENT 
FLD— ELEMENT 
TEXT-ELEMENT 

■  Report.def 

■  Loop  Selectors 

ELEMENT 

BAND-ELEMENT 

BOX-ELEMENT 

FLD— ELEMENT 

TEXT-ELEMENT 

RULER-ELEMENT 

PARA_ELEMENT 

PAGE-ELEMENT 
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Example 


( 

DEFINE  menu_hlp(mhead, inline) ; 

II 

II  THIS  UDF  IS  USED  FOR  PROCESSING  MENU  LEVEL  HELP  TEXT 

II 

EndofpageO;  .  - 

Print_Head=l; 

FOREACH  MENU_HELP 
IF  MENU_HELP  THEN 
IF  Print_Head  THEN 
PRINT (cr 1 f+mhead+crl f+ml  i  ne+cr  1  f ) ; 

LMARG ( 2 ) ; 

Print_Head=0; 

ENDIF 

PRINT ( RTR IM (MENU_HELP) +crl f ) ; 
endofpageO ; 

ENDIF 

NEXT; 

endofpageO ; 

LMARG(O) ; 

RETURN; 

ENDDEF;  } 


In  this  example  the  loop  selector  MENU-HELP  is  used.  The  details  of  this 
selector  are  in  Applctn.def.  It  is  a  frame-level  selector  that  can  occur  in  all 
design  object  files  except  an  application  object  file.  You  must  therefore 
check  for  it  at  the  frame  level  of  the  correct  design  object  file.  The 
Menu _ hlp( )  UDF  is  called  from  within  a  template  which  is  already  referenc¬ 

ing  a  specific  design  object  file. 

It  is  not  necessary  to  explicitly  declare  a  cursor  variable  if  it  is  not  going  to 
be  referenced  by  another  expression  or  loop. 

An  example  of  when  to  explicitly  declare  a  cursor  variable  can  be  found 
in  the  sample  template  of  Chapter  2.  Line  224  begins  a  FOREACH  TREE 
loop  with  the  related  cursor  variable  Menu.  This  loop  is  designed  to  refer¬ 
ence  all  design  object  files  of  a  particular  application.  Then  it  must  reference 
information  within  the  particular  design  object  file.  On  line  348,  another 
FOREACH  loop  begins.  FOREACH  FLD— ELEMENT  Fids  IN  Menu  loops 
through  the  FLD—ELEMENTs  occurring  in  the  design  object  file  currently 
referenced  by  Menu. 


TEMPLATE  LANGUAGE 
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DO...  WHILE/UNTIL.. .ENDDO 

This  construction  is  similar  to  the  dBASE  command  in  that  it  allows  state¬ 
ments  between  it  and  its  associated  ENDDO  to  be  repeated  while  the  spec- 
ifed  condition  is  true. 

Command  Syntax 

DO  [  <  commands  >  ]  WHILE/UNTIL  [  <  condition  >  ]  ENDDO 

Rules 

Statements  which  appear  between  the  DO  and  the  WHILE  will  be  executed 
at  least  once. 

Statements  between  the  WHILE  and  the  ENDDO  are  executed  after  the 
WHILE  test.  If  the  test  returns  false,  the  statements  will  not  be  executed. 

If  UNTIL  is  used  in  place  of  WHILE,  the  test  is  reversed.  Statements  between 
the  UNTIL  and  the  ENDDO  will  be  executed  before  the  test.  Even  if  the  test 
returns  false,  the  statements  will  have  been  executed  once. 

Both  WHILE  and  UNTIL  mav  be  used  to  conditionally  exit  from  the  FOR  and 
FOREACH  loops. 


FOR.. .NEXT 

This  construction  is  often  used  for  incremental  looping. 

Command  Syntax 

FOR  <  vamame  >  =  <expNl>  TO  <expN2>  [STEP  <  constant  >] 
...NEXT  [  <  vamame  >  ] 

Rules 

The  counter  <  vamame  >  is  declared  by  the  FOR  statement.  It  is  initialized 
to  <  expN  1  >  . 

The  test  FOR  <  vamame  >  <  =  <  expN2  >  is  performed  at  the  start  of  the 
loop.  If  <  vamame  >  <  =  <  expN2  >  the  loop  is  performed.  NEXT  incre¬ 
ments  <  vamame  >  by  <  constant  >  .  The  loop  may  be  executed  from  none 
to  many  times  depending  on  the  results  of  the  test. 

If  STEP  is  not  specified,  NEXT  increments  by  one. 

You  may  use  the  ENUM  command  to  assign  a  readable  symbol  to 
<  constant  >  . 
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EXIT 


This  command  leaves  the  current  loop  and  control  is  passed  to  the  first  state¬ 
ment  following  the  loop  construct. 


LOOP 


Command  Syntax 

Beginning  of  loop  [EXIT]"  End  of  loop 

Rules 

This  command  mav  be  used  in  anv  of  the  loop  constructs:  DO  WHILE, 
FOREACH,  and  FOR. 

Control  is  passed  to  the  command  following  the  NEXT  or  ENDDO  statement. 


This  command  jumps  back  to  the  beginning  of  the  current  loop. 

Command  Syntax 

Beginning  of  loop  [LOOP]  End  of  loop 


Rules 

Inside  a  FOREACH  or  FOR  loop,  control  advances  to  the  next  WHILE  or 
UNTIL  test. 

If  there  is  no  WHILE  or  UNTIL  test,  the  current  cursor  or  counter  is  incre¬ 
mented  and  control  is  passed  to  the  starting  FOREACH  or  FOR. 

Inside  a  DO  WHILE,  control  advances  to  the  next  WHILE  or  UNTIL  test.  If 
there  is  no  test,  control  passes  to  the  top  of  the  DO  loop. 
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Functions 


ALLTRIM(  <  expC  >  ) 

The  ALLTRIM( )  function  trims  all  leading  and  trailing  blank  characters 
around  a  string. 


Usage 

This  function  allows  you  to  handle  a  character  string  without  its  leading 
and  trailing  blanks.  The  ALLTRJM( )  function  allows  you  to  format  messages 
easily. 


Example 

{VAR  a,  b; 
a="  Ashton-Tate 
b=ALLTRIM( a) ; 

PRINTC'First  example  is  "+a+"."); 
PRINT  ("Second  example  is  "+b+".")} 

This  will  print  the  following: 

First  example  is  Ashton-Tate 
Second  example  is  Ashton-Tate. 


APPEND(  <  filename  >  ) 

The  APPEND()  function  concatenates  text  to  the  end  of  an  existing  text  file. 
If  the  named  file  does  not  exist,  it  will  be  created. 


Usage 

This  function  allows  you  to  add  text  to  a  file. 
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Example 

(IF  FILEEXIST( "Some. app" )  THEN 
APPEND( "Mai nmenu . prg" ) 

00  MAIN 
ELSE 

APPEND! "Mai nmenu . prg" ) 

DO  ERRORS 
ENDIF) 


This  example  tests  for  the  existence  of  the  Some.app  file.  If  the  file  is  in  the 
default  directory,  the  text  DO  MAIN  is  placed  in  the  Mainmenu.prg  file.  Oth¬ 
erwise  the  text  DO  ERRORS  is  added  to  the  Mainmenu.prg  file. 


<  filename  >  .out. 


NOTE 

Each  main  template  should  have  either  a  CREATEf )  or  APPEND( ) 
function  near  the  start,  otherwise  output  will  go  to  a  file  called 


ASC(  <  expC  >  ) 

The  ASC()  function  returns  the  ASCII  value  of  the  first  character  of  a  string. 

Usage 

This  function  enables  you  to  determine  the  ASCII  value  of  the  character  at 
the  far  left  of  the  string.  You  may  use  the  result  as  a  flag  or  as  an  indication 
of  upper  or  lower  case. 


Example 

(PRINT (ASC ( "alphabet" ) ) ) 


This  will  print  the  ASCII  value  of  a,  which  is  97. 


ASKUSER(  <  expCI  >  ,  <  expC2  >  ,  <  expN  >  ) 

The  ASKUSER( )  function  opens  a  box  in  which  it  shows  the  prompt  string 
(  <  expCI  >  ),  displays  a  default  answer  string  (  <  expC2  >  ),  and  assigns  a 
maximum  length  for  input  (  <  expN  >  ).  (78  is  the  maximum  length  that  can 
be  specified.)  The  response  is  captured  to  a  previously  named  variable. 


Usage 

This  function  allows  you  to  prompt  the  user  during  the  template  generation 
process  for  specific  information,  such  as  a  filename. 
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Example 


(VAR  filename; 

IF  NOT  MENUJIEW  THEN 
filename=ASKUSER("Please 
enter  a  database  name", "Client. dbf", 12) 
ENDIF) 


The  selector  MENU-VIEW  is  checked.  If  it  is  null,  the  template  asks  the  user 
to  enter  a  filename.  The  value  entered  is  assigned  to  the  Filename  variable. 


AT(  <  expCI  >  ,  <  expC2  >  ) 

The  AT()  function  performs  a  substring  search.  It  returns  the  location  of 
<  expCI  >  in  <  expC2  >  .  Zero  (0)  is  returned  if  <  expCI  >  is  not  found 
in  <  expC2  >  . 


Usage 

This  function  allows  you  to  determine  the  existence  of  embedded  informa¬ 
tion,  or  to  locate  the  starting  position  of  information  you  wish  to  use. 


Example 


(VAR  location; 

location=AT( "Prog", "Advanced  Programmer's  Guide"); 
PRINT( 1 ocati on) } 


The  Location  variable  will  hold  the  value  10. 


ATALPHA(  <  expC  > ) 

The  ATALPHA( )  function  finds  the  first  non-blank  alphanumeric  character 
in  the  expression. 


Usage 

This  function  allows  you  to  ignore  blanks  and  proceed  to  the  beginning  of 
essential  text. 
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Example 

(VAR  location; 

location=ATALPHA("  Edit  Client  Info"); 

PRINT(location)} 

The  Location  variable  will  hold  the  value  2,  since  the  first  non-blank  charac¬ 
ter  is  in  position  2  of  the  string. 


ATOMC(  <  cursor  >  ,  <  expN  >  ) 

ATOMC()  returns  the  attribute  value  of  the  selector  referenced  by  the  cursor 
variable  and  the  IID  given  by  <  expN  >  . 


Usage 

This  function  allows  you  to  reference  selectors  by  number  rather  than  name. 


Example 


(FOREACH  FLD_ELEMENT  k  > 

field  (k)  the  value  of  selector  123  is  CATOMC ( k , 123) > 

(NEXT  k; 

done:) 


NOTE 

The  ATOMCf)  function  is  part  of  the  implementation  of  the  FOREACH 
loop,  but  it  may  be  called  directly. 


BACKSLASH() 

The  BACKSLASHQ  function  inserts  a  backslash  (\)  into  the  output  text 
file.  This  function  is  convenient  because  of  the  special  meaning  of  the  back¬ 
slash  within  the  Template  Language.  A  backslash  (\)  within  command  braces 
is  the  instruction  to  ignore  the  special  meaning  of  the  next  character.  Out¬ 
side  curly  braces,  at  the  end  of  a  line,  it  means  ignore  the  carriage  return 
linefeed. 


Usage 

This  function  allows  you  to  reference  path  names. 
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Example 

The  following  three  lines  all  do  the  same  thing. 

d:  (BACKSLASHOJTest.prg 
{PRINK  "d:  Wtest .  prg" ) } 
d:\test.prg 


BREAKPOINT!  <  expC  >  ) 

The  BREAKPOINT!)  function  displays  the  value  of  the  specified  expression 
and  requests  the  level  of  debugging  action  to  implement.  See  DEBUG! ) 
for  an  explanation  of  debug  levels.  The  breakpoint  expression  will  be 
written  to  the  list  file  specified  by  using  the  -1  option  of  the  dGEN 
stand-alone  interpreter. 


Usage 

This  function  allows  you  to  specify  an  interruption,  for  debugging  purposes, 
in  the  normal  running  of  your  template. 


Example 


(VAR  temp;  temp  =  1; 

FOR  i  =  1  TO  10 

BREAKPOINT ( "The  value  of  temp  is"  +  STR< temp) ) ; 
gettempO;//  user-defined  function 
NEXT 
} 


CGET() 

The  CGET()  function  waits  for  any  key  to  be  hit  and  captures  the  keystroke. 


Usage 

This  is  useful  for  determining  what  action  the  user  has  just  taken. 


Example 


(VAR  key;  key-"";  PMSGC'Continue  Y/N?") ; 
DO  WHILE  NOT  AKupper(key)  ,"YN") 
key=CGET ( ) ; 

ENDDO) 
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CHR(  <  expN  >  ) 

This  function  returns  a  one-character  string  from  an  ASCII  value.  The 
<  expN  >  range  is  0-255. 


Usage 

This  function  allows  you  to  display  characters  for  which  there  may  be  no 
keyboard  equivalent.  By  concatenating  them  together,  you  can  create  your 
own  boxes  or  other  graphic  shapes. 


Example 

<  PRINT (CHR(24) )> 

This  example  will  output  an  up  arrow. 


CLS() 


This  function  clears  the  screen  and  positions  the  cursor  to  the  home  location 

0,0. 

Usage 

This  enables  you  to  clear  the  entire  screen  in  readiness  to  write  more  infor¬ 
mation  to  it.  There  are  no  arguments  allowed  for  this  function. 


Example 

<CLS ( ) > 


COL1() 


This  function  returns  the  number  of  the  first  column  of  an  object  frame.  If 
there  is  no  frame,  0  is  returned. 


Usage 

This  function  allows  you  to  determine  the  specific  size  of  an  object. 


Example 


9  (ROWIOMCOLIO)  TO  {R0W2OMC0L2O) 


This  example  will  output  dBASE  code  for  a  specific  size  box. 
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COL2() 


This  function  returns  the  number  of  the  last  column  of  an  object  frame.  If 
there  is  no  frame,  79  is  returned. 


Usage 

This  function  allows  you  to  determine  the  specific  size  of  an  object. 


Example 

8  (ROWIOMCOLIO)  TO  {R0W2()),{C0L2O> 

This  example  will  output  dBASE  code  for  a  specific  size  box. 


COPY(  <  filename  >  ) 

This  function  copies  the  contents  of  the  named  text  file  into  the  current  out¬ 
put  text  file. 


Usage 

This  function  allows  you  to  insert  information  from  auxiliary  files  into  the 
output  file. 


Example 


{CREATEC'myproc.prg") ; 
C0PY("proc_l ib.prg") > 


CPUT(  <  expC  >  ) 

This  function  writes  the  specifed  string  at  the  current  location  of  the  screen 
cursor. 

Usage 

This  function  allows  you  to  place  messages  anywhere  on  the  screen  or  to 
selectively  clear  parts  of  the  screen. 


Example 

(CURS0R_P0S  (23,0);  CPUKSPACE  (80));) 
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CREATE(  <  filename  >  ) 

This  function  creates  and  opens  a  named  text  file.  Text  output  prior  to  the 
CREATE  or  APPEND  functions  goes  to  a  file  called  <  object  name  >  .out. 


Usage 

This  function  allows  you  to  specify  the  text  file  for  the  output  of  your 
template. 


Example 

{CREATEO'test.prg")) 


or 


{a="test.prg"; 
CREATE (a)} 


CURLINE() 

This  function  returns  the  current  line  number  being  output.  It  is  reset  to  0 
when  PAGEJECTQ  is  executed. 

Usage 

This  function  allows  you  to  do  your  own  page  formatting  for  the  text  being 
placed  in  the  output  file. 


Example 


(linecnt-CURLINEO; 
IF  linecnt  >  60  THEN 
PAGEJECTO 
ENDIF) 


CURSOR_POS(  <  expN,expN  >  ) 

This  function  places  the  cursor  at  the  specified  row  and  column  on  the 
screen.  Row  and  column  are  zero-based,  with  0,0  meaning  the  top  left 
corner. 
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Example 

1  CURS0R_P0S  (23,0) ;  CPUTCSPACE  (80));) 


DATE() 


This  function  returns  the  system  date  and  time  in  the  format:  5-31-87  2:30p. 


Usage 

This  function  allows  you  to  document  the  date  and  time  you  generate  the 
program.  This  can  be  important  when  debugging  or  doing  maintenance  so 
that  you  know  the  version  with  which  you  are  working. 


Example 

Application  Date:  (DATEO) 

This  would  print  Application  Date:  5-31-87  2:30p. 


DEBUG(  <  expN  >  ) 

This  function  determines  the  amount  and  type  of  information  output  in  addi¬ 
tion  to  the  normal  action  of  running  a  template.  This  information  may  be 
traced  by  setting  <  expN  >  from  0  to  6. 

0  =  No  traces,  no  display  of  generated  text,  no  keyboard  interrupts 

1  =  Display  generated  text 

2  =  Display  generated  text  and  monitor  keyboard  for  interrupts 

3  =*  Display  generated  text  and  template  code  stream,  and  monitor 

keyboard  for  interrupts 

4  =  Display  generated  text  and  template  code  stream,  and  single-step 

through  the  template  code  stream 

5  =  The  same  as  3,  but  also  trace  stack  and  assembly  code 

6  =  The  same  as  4,  but  also  trace  stack  and  assembly  code  and  single  step 

on  assembly  instructions  rather  than  source  lines 


Usage 

Levels  2  and  3  interrupts  allow  the  input  of  new  level  numbers,  0  through  6. 

Levels  5  and  6  code  streams  are  sent  to  tlie  list  file  specified  in  the  -1  option 
of  the  dGEN  command  line.  Please  see  Chapter  7  for  more  information. 
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NOTE 

This  function  is  primarily  for  use  with  the  dGEN  template  interpreter. 


Example 

(IF  myvar  —  0  THEN  DEBUG(3) ; -ENDIF) 


EOC(  <  cursor  >  ) 

This  function  tests  whether  the  cursor  variable  has  reached  the  end  of  the 
set.  If  there  are  more  elements  of  the  set,  a  0  is  returned.  If  the  end  has  been 
reached,  1  is  returned. 


Usage 

This  function  allows  you  to  test  if  the  entire  set  has  been  scanned. 


Example 


{FOREACH  FLDJLEMENT  k  }  field  {k> 

(NEXTC(k); 

IF  EOC(k)  THEN  GOTO  done;} 

(NEXT  k; 
done:} 

This  example  loops  through  the  fields  referenced  by  the  cursor  variable  k. 
The  EOC()  function  tests  to  see  if  the  cursor  has  advanced  beyond  the  end 
of  the  set  of  fields. 


NOTE 

This  function  is  part  of  the  implementation  of  the  FOREACH  loop. 
However,  it  is  available  to  be  used  directly. 


EXEC(  <  filename  >  ) 

This  function  is  used  to  run  external  programs  when  a  template  is  operating 
under  the  dGEN  stand-alone  interpreter. 


Usage 

This  function  executes  the  DOS  command  line  specified  by  <  filename  >  . 
Template  processing  continues  upon  completion  of  the  DOS  action. 
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Example 

(EXEC ("dir  *.prg");) 


FILEDATE(  <  filename  >  ) 

This  function  returns  the  date  and  time  the  specified  file  was  created  or  last 
saved.  The  date  is  returned  in  the  form  YYYY-MM-DD.  The  time  is  returned 
as  HH:MM:SS  (24-hour  clock). 


Usage 

This  is  useful  for  keeping  track  of  template  versions  during  development. 


Example 

(VAR  fdate;  fdate  =  FILEDATE  ("menu. gen")} 


FILEDRI VE(  <  filename  >  ) 

This  function  returns  the  drive  letter  from  a  filename  that  may  contain  a 
drive  and  path. 


Usage 

This  function  determines  the  drive  letter  so  that  you  may  write  additional 
files  to  that  drive  or  avoid  using  it. 


Example 


(VAR  drive; 

dri ve-FILEDRIVE( "d : \test\test .dbf " ) ; 
PRINT (dri ve) > 


This  will  print  the  drive  letter  d. 


FILEERASE(  <  filename  >  ) 

This  function  erases  the  specified  filename.  The  current  directory  is  assumed 
unless  a  drive  or  path  is  specified.  If  a  drive  or  path  is  given,  the  filename  is 
treated  as  unambiguous. 
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Usage 

This  function  returns  the  value  1  (true)  if  the  file  was  deleted.  If  the  file 
could  not  be  deleted,  0  (false)  is  returned. 


Example 


(VAR  myfile;  myfile  =  "mytest.doc"; 

IF  FILEEXIST (myfi le)  THEN  F I LEERASE (myf l 1 e )  ENDIF} 


FILEEXIST(  <  filename  >  ) 

This  function  tests  for  the  existence  of  a  file  on  a  disk. 


Usage 

This  function  allows  you  to  determine  the  existence  of  a  named  file  on  disk. 
If  it  does  not  exist,  for  example,  you  may  have  to  prompt  the  user  for  a  cor¬ 
rect  entry. 


Example 


(VAR  filename; 
filename="custmast.dbf  ; 

IF  NOT  FILEEXIST ( fi 1 ename)  THEN 

PAUSE ( "Fi 1 e  "+filename+"  does  not  exist") 
ENDIF) 


FILENAME!  <  filename  >  ) 

This  function  extracts  the  filename  and  extension  from  a  fully  specified  path. 

Usage 

This  function  returns  just  the  filename  and  dot  extension,  as  a  file  may  be 
kept  in  different  subdirectories  on  different  systems. 

Example 

{  x  =  FILENAME("c:\\db4\\test\\apps\\myprog.app")  ) 

The  filename  is  (x> 

This  would  print  The  filename  is  myprog.app. 
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FILEOK(  <  filename  >  ) 

This  function  checks  for  a  valid  DOS  filename. 


Usage 

This  function  is  useful  in'  trapping  user  data  entry  errors  at  the  time  of 
template  generation. 


Example 

(VAR  filename; 

fi  1  ename= 1  testWdoc .  prg" ; 

IF  FILEOK(filename)  THEN 
CREATE! filename) 

ELSE 

filename=ASKUSER( "Please  enter  a  valid  filename", "",12) 
!  ENOIF) 


This  checks  whether  the  Filename  variable  holds  a  valid  DOS  filename.  If  so, 
the  file  is  created.  If  not,  the  program  asks  for  a  valid  filename. 


FILEPATH(  <  filename  >  ) 

This  function  returns  the  path  portion  of  a  complete  filename. 


Usage 

This  function  isolates  the  path  from  the  full  description  of  the  named  file. 
It  is  useful  when  creating  additional  files. 


Example 


(VAR  path,  filename; 

fi  1  ename="c :  WapgenWtest .  prg" ; 

path=FILEPATH( filename)) 


This  results  in  the  variable  path  holding  \apgen\. 


FILEROOT(  <  filename  >  ) 

This  function  returns  the  root  of  a  filename  (up  to  eight  characters). 


Usage 

This  function  isolates  the  filename,  up  to  the  first  eight  characters,  from  the 
full  description.  This  allows  you  to  name  subsidiary  files  with  the  same  root 
but  different  extensions. 
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Example 

(VAR  filename,  root; 
f  i  1  ename= "c :  WapgenWmyapWtest .  prg" ; 
root=F I LEROOT ( f i 1  enamel ) 


This  results  in  the  variable  root  holding  the  root  of  the  Test  filename. 


FILESIZE(  <  filename  >  ) 

This  function  returns  the  size  of  the  specified  file. 


Usage 

This  function  is  useful  in  file  comparison. 


Example 


(VAR  fsize; 

fsize  =  FILESIZE  ("menu. gen11)} 


FILETYPE(  <  filename  >  ) 

This  function  returns  the  three-character  extension  of  a  filename. 


Usage 

This  allows  you  to  check  for  the  existence  of  a  particular  kind  of  file  and  act 
upon  the  resulting  type. 


Example 


(VAR  filename,  ext; 
f  i  1  ename="c :  WtestWtest .  prg" ; 
ext=F I LETY  PE ( f i 1 ename ) } 


This  results  in  the  variable  ext  holding  the  file  extension  prg. 


GETENV(  <  expC  >  ) 

This  function  returns  the  value  of  a  DOS  environment  variable.  The  result  is 
a  string  or  null  if  not  found. 
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Usage 


This  allows  you  to  check  specific  DOS  environmental  variables  and  act 
accordingly. 


Example 

(GENTENVC'PATH")} 


This  example  returns  the  current  DOS  path  string. 


IIDC(  <  cursor  >  ) 

This  function  returns  the  integer  selector  value  of  the  attribute  pointed  to  by 
the  cursor.  The  result  is  a  number. 


Usage 

This  allows  you  to  determine  the  existence  of  a  specific  attribute  by  its  inter¬ 
nal  identification  number.  The  names  of  selectors  in  an  INCLUDE  file  may 
be  changed,  but  the  numbers  must  remain  the  same. 


Example 


(FOREACH  ATTRIBUTE  k  } 

attribute  (k)  is  iid  UIDC(k)}  with  a  value  of  (VALC ( k) > 
of  type  (TYPEC(k)} 

{NEXT  k;} 


LEN(  <  expC  >  ) 

This  function  returns  the  length  of  the  specified  string. 


Usage 

You  will  often  want  to  know  the  actual  length  of  a  string  that  may  have  been 
trimmed  or  extracted.  You  may,  for  example,  have  only  a  certain  number  of 
positions  in  which  to  print  some  information. 


Example 


(VAR  menuname; 
menuname="Budgets" ; 
PRINT! LEN( menuname) ) ) 


This  prints  a  7,  the  length  of  the  menu  name. 
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LMARG(  <  expN  >  ) 

This  function  sets  the  left  margin  for  subsequent  text  output.  A  negative 
argument,  0,  or  1  will  reset  the  margin  to  1. 


Usage 

This  function  helps  format  your  text  output.  You  could  use  it  to  provide 
more  readable  code  for  documentation  purposes. 


Example 


action=0 
escape=27 
ret2cal ler=23 

DO  WHILE  .NOT.  (action  =  ret2caller  .OR.  LASTKEYO  =  escape) 
(LMARG(4)> 

ACTIVATE  POPUP  (MENU  NAME) 

DO  CASE 

CASE  BARO  =  { R0W_P0S I TN } 

{ LMARG( 7 ) ) 

{// 

II  command  related  to  this  action 

II) 

action={MENU  ACT} 

{ LMARG ( 4 ) > 

ENDCASE 
{ LMARG ( 1 ) } 

ENDDO 


In  this  example  the  generated  dBASE  code  is  for  a  pop-up  menu  to  be  reacti¬ 
vated  unless  the  action  is  return  to  caller  or  the  last  key  pressed  was  Esc. 
Although  the  code  in  the  example  is  flush  to  the  left,  LMARGQ  will  indent 
the  code  by  3  spaces  and  by  6  spaces.  LMARG(l)  resets  the  output  text 
stream  to  the  beginning  of  the  line. 


LOWER(  <  expC  >  ) 

This  function  converts  a  string  to  lower  case. 

Usage 

This  function  helps  style  your  output.  You  can  convert  an  all  upper-case 
response  into  an  initially  capitalized  word. 
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Example 

(VAR  test , test2 ; 
test="APPLICATION" ; 
test2-SUBSTR( test, 1,1) 

-♦-LOWER  ( SUBSTR  (test ,  2 ,  LEN  ( test  )-l ) ) } 

The  Test 2  variable  will  hold  the  word  Application.  Everything  to  the  right  of 
the  first  character  has  been  converted  to  lower  case. 


LTRIM(  <  expC  >  ) 

This  function  trims  the  leading  blanks  of  a  string. 


Usage 

This  function  enables  you  to  format  a  line  of  text  by  eliminating  the  blanks 
in  front  of  a  word. 


Example 


;  (VAR  mstring,mstring2; 
j  mstring="  Application"; 

mstring2-LTRIM(mstring) ; 
!  PRINT(mstring2)} 


This  results  in  the  printing  of  just  the  word  Application  without  the  blank  in 
front  of  it. 


MAKEC(  <  expN  >  [,  <  cursor  >  ]) 

This  function  creates  a  cursor  using  the  internal  selector  number.  Use  the 
construction  @  <  selector  >  for  expN.  Use  <  cursor  >  if  creating  a  DOS  file 
cursor. 


NOTE 

All  DOS  file  specifications  are  valid  for  expC  (for  example,  *.popj. 


Usage 

This  function  enables  you  to  declare  a  specific  cursor  variable  independently 
of  the  FOREACH  construct. 


Example 

1  J7  MAKEC(@FLD_ELEMENT) 
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MAX(  <  expN  >  ,  <  expN  >  ) 

This  function  returns  the  maximum  value  of  two  numeric  expressions. 


Usage 

Bv  comparing  assorted  pairjs  t>f  numbers  with  this  function,  you  can  isolate 
the  largest  number. 


Example 


(VAR  resul t,numl,num2; 

numl=10; 

num2=20; 

resul t=MAX(numl ,num2) ; 
PRINT  <  resul t ) } 


The  number  printed  is  20,  the  larger  of  the  two  variables. 


MIN(  <  expN  >  ,  <  expN  >  ) 

This  function  returns  the  minimum  value  of  two  numeric  expressions. 


Usage 

By  comparing  assorted  pairs  of  numbers  with  this  function,  you  can  isolate 
the  smallest  number. 


Example 


{VAR  resul t,numl ,num2; 

numl=10; 

num2=20; 

resul t=MlN(numl,num2) ; 
PRINT( result)) 


The  number  printed  is  10,  the  lower  of  the  two  variables. 


NEWFRAME(  <  expC  >  ) 

This  function  allows  you  to  change  the  current  object  being  worked  on  by 
the  Template  Language.  A  0  is  returned  if  the  change  is  successful,  a  1  if  not. 
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Usage 

This  function  is  used  during  generation  so  that  multiple  related  objects 
can  be  processed  in  one  run.  Its  primary  use  in  the  Applications  Generator 
is  to  load  the  main  menu  specified  in  the  application  object.  The  command 
FOREACH  TREE.. .NEXT  then  automatically  loads  objects  further  down  the 
tree. 


Example 


NEWFRAME ( "myprog . pop" ) 


or 


NEWFRAME ( MENU_MA I N ) 

In  the  second  example,  MENU-MAIN  is  a  selector  defined  in  Applctn.def. 


NEXTC(  <  cursor  > ) 

This  function  allows  you  to  advance  the  specified  cursor  by  one  position. 
There  is  no  return  value. 


Usage 

This  function  directly  adjusts  the  cursor  position  beyond  the  normal  single 
step  of  the  FOREACH.. .NEXT  construct. 


Example 


I  (FOREACH  FLD_ELEMENT  k  > 
field  (k> 

(  NEXTC(k) ;} 
j  (NEXT  k;> 


This  example  moves  the  cursor  to  every  other  field. 


NMSG(  <  expC  >  ) 

This  function  displays  a  message  on  the  navigation  line.  This  is  line  23  in 
normal  mode  and  line  41  in  43-line  EGA  mode. 


Usage 

The  message  is  centered  on  the  navigation  line,  and  characters  beyond  80 
are  truncated. 
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Example 

vNMSGC'Any  key  to  continue...");} 


NUMSET(  <  expN  >  ) 

This  function  allows  you  to  determine  the  internal  numeric  setting  of  dBASE 
indicators.  They  are  defined  and  documented  in  Builtin.def.  If  the  template 
is  run  in  dGEN,  NUMSETQ  will  return  0  for  all  dBASE  settings  that  are 
checked  since  it  is  not  in  dBASE. 


Usage 

NUMSETQ  ascertains  the  state  of  a  specific  dBASE  internal  setting. 


Example 


{NUMSET (_FLGCL0CK) > 


This  example  returns  a  1  if  the  clock  is  set  on,  0  if  the  clock  is  set  off. 


NOTE 

_ FLGCLOCK  is  one  of  the  setting  arguments  specified  by  the  ENUM 
command  in  3uiltin.def. 


PAGEJECT() 

This  function  outputs  a  CHR(12),  the  page  eject  character.  It  also  resets  the 
CURLINE()  function  line-count  to  0. 


Usage 

You  can  format  your  output  text  into  pages  with  this  function.  With 
additional  coding,  you  can  provide  headings  and  footers  for  your 
documentation. 


Example 


(IF  CURIINEO  >  60  THEN 
page*+l; 

PAGEJECTO 

ELSE 

GOTO  begin 
ENDIF) 
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PAGEL(  <  expN  >  ) 

This  function  sets  a  constant  page  length  for  vour  output.  A  negative  argu¬ 
ment  is  the  same  as  PAGEL(O)  for  no  page  breaks. 


Usage 

If  you  do  not  need  conditional  page  ejects,  this  is  an  easv  way  to  format  the 
text  output  for  documentation  templates. 


Example 


(VAR  file,  page,  counter; 
PAGEK62) ;) 


This  sets  the  default  page  length  for  the  output  to  62  lines  per  page.  After 
every  62  lines,  a  page  eject  character  is  inserted  and  CURLINE()  is  reset  to 
0. 


PATHEXIST(  <  expC  >  ) 


This  function  returns  a  1  if  the  path  exists,  0  if  it  does  not. 


Usage 

This  is  useful  for  validating  the  path. 


Example 

{ PATHEX I  ST(  "C :  WOOS" ) ) 


PAUSE(  <  expC  > ) 

This  function  halts  template  interpretation  and  displays  a  message  to  the  user 
on  line  24  or  42  depending  on  the  display  size.  The  system  waits  for  any  key¬ 
stroke  before  continuing. 


Usage 

This  function  is  helpful  for  debugging  templates. 
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Example 

{VAR  filename; 
filename="test.prg"; 

IF  NOT  FILEEXISKfi  lename)  THEN 

PAUSE ("File  "+filename+"  is  not  in  current 
directory") 

ENDIF) 


PMSG(  <  expC  >  ) 

This  function  displays  the  specified  message  on  the  prompt  line.  This  is  line 
24  in  normal  mode,  and  line  42  in  the  43-line  EGA  mode. 


Usage 

The  message  is  centered  on  the  prompt  line,  and  characters  beyond  80  are 
truncated. 


Example 

{PMSGC'Any  key  to  continue...");) 


POKE(  <  expC  >  ,[  <  expC  >  ...]) 

This  inserts  the  specified  character  expression  into  the  text  without  any 
formatting. 


Usage 

This  allows  a  CHR(10)  linefeed  without  the  carriage  return  added  by  the 
PRINTQ  function. 


Example 

t  POKE ( CHR10 ) ) 


PRINT(  <  expC  >  ) 

This  function  outputs  the  character  expression  into  the  text  file. 


NOTE 

A  carriage  return  is  automatically  inserted  after  a  linefeed  character, 
CHR(IO).  CURLINEI )  and  LMARGf )  settings  are  still  maintained. 
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Usage 

You  may  use  this  function  to  output  text  within  the  command  structure. 


Example 

(VAR  mstring,  crlf; 
mstring  =  "Application 
crlf  =  CHR(IO); 
PRINT(mstring+crlf)} 


REPLICATE(  <  expC  >  ,  <  expN  >  ) 

This  function  repeats  the  specified  character  expression  <  n  >  times. 


Usage 

This  function  is  useful  for  creating  lines  and  other  pictoral  elements. 


Example 


(VAR  a, crlf; 
crl f=CHR( 10) ; 
a="Appl ication:  "+name; 

PRINT  (a+crlf) ; 

PRINK  REPLICATE ("-",LEN (a) )  )> 


The  word  Application:  plus  the  entered  name  will  be  underlined. 


ROW1() 

This  function  returns  the  number  of  the  first  row  of  an  object  frame.  If  there 
is  no  frame,  0  is  returned. 

Usage 

This  function  allows  you  to  determine  the  specific  size  of  an  object. 

Example 

j  9  (ROWIOMCOLIO)  TO  {R0W2 ()>,€C0L2()} 

This  example  will  output  dBASE  code  for  a  specific  size  box. 
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ROW2() 

This  function  returns  the  number  of  the  last  row  of  an  object  frame.  If  there 
is  no  frame,  24  is  returned. 


Usage 

This  function  allows  you  to  determine  the  specific  size  of  an  object. 


Example 

9  {ROWIOMCOLIO)  TO  {R0W2()},{C0L2()> 


This  example  will  output  dBASE  code  for  a  specific  size  box. 


RTRIM(  <  expC  >  ) 

This  function  removes  the  trailing  blanks  from  a  string. 

Usage 

This  is  useful  for  eliminating  trailing  spaces  in  evaluating  a  string. 

Example 

(VAR  test; 

I  test="Appli cation 
|  PRINT( LEN ( RTRIM( test ) > ) > 

This  results  in  11,  the  length  of  the  string  without  the  trailing  blanks. 


SCREEN!  <  expN  >  ) 

This  function  extracts  a  line  from  a  screen  object. 


Usage 

SCREEN!)  is  helpful  when  documenting  menus. 
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Example 

(VAR  scrnjine; 
scrn  line-1; 

I  PRINK  SCREEN ( scrn _1 i ne) ) > 

This  will  print  line  1  of  the  work  surface  to  the  text  file. 


SETC(  <  cursor  >  ,  <  expN  >  ) 

This  function  moves  the  specified  cursor  to  a  new  relative  position. 


Usage 

Although  it  is  part  of  the  internal  implementation  of  the  FOREACH  loop,  this 
function  may  be  used  directly  to  adjust  the  cursor  position. 

Example 

(FOREACH  FLD_ELEMENT  k>  Field  (k>  (  SETC(k,2) ; }  (NEXT  k;} 


This  example  advances  the  cursor  k  by  two  positions.  The  loop  has  the  effect 
of  visiting  every  third  field. 


SPACE(  <  expN  >  ) 

This  function  inserts  the  specified  number  of  blanks  into  the  text  file. 

Usage 

This  function  is  helpful  for  formatting  documentation  templates. 

Example 

(VAR  page; 
page-1; 

PR  I  NT  Page  "+page+SPACE  ( 55 )  +DATE  ())} 

This  example  will  print  the  page  number  and  the  date  70  spaces  apart. 


STR(  <  expN  >  ) 

This  function  converts  a  number  to  a  string. 


TEMPLATE  LANGUAGE 


5-25 


JOBNAME:  No  Job  Name  PAGE:  26  SESS:  8  OUTPUT:  Fri  Jul  29  21:29:53  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpchapS 


Usage 

This  function  allows  you  to  convert  a  numeric  type  to  a  character  type  in 
order  to  print  the  number  as  part  of  a  character  string. 


Example 

(VAR  numl,num2; 

numl=34; 

num2=numl*12; 

PRINT ( "The  number  is  "+ALLTRIM(STR(num2) ) )} 
This  will  print  The  number  is  408. 


STRSET(  <  expN  >  ) 

This  function  allows  you  to  determine  the  internal  character  setting  of 
dBASE  indicators.  They  are  defined  and  documented  in  Builtin.def.  Nulls 
will  be  returned  for  any  dBASE  setting  referenced  when  the  template  is  run 
from  the  dGEN  stand-alone  interpreter. 


Usage 

STRSET()  ascertains  the  state  of  a  specific  dBASE  setting. 


Example 

{STRSET (_DEFDRIVE) > 


This  example  would  return  a  D  if  the  dBASE  default  drive  had  been  set  to  D. 


NOTE 

_ DEFDR1VE  is  one  of  the  setting  arguments  declared  by  the  ENUM 
command  in  Builtin.def. 


SUBSTR(  <  expC  >  ,  <  expNI  >  [,  <  expN2  >  ]) 

This  function  extracts  a  substring  from  <  expC  >  .  starting  at  location 
<  expNI  >  for  <  expN2  >  characters.  If  <  expN2  >  is  not  specified, 
the  substring  to  the  end  of  <  expC  >  is  returned. 

Usage 

This  function  is  useful  for  isolating  a  portion  of  a  character  string. 
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Example 

<VAR  test , test2 ; 

test  =  "Empire  State  building"; 

test2  =  SUBSTR(test,AT("S",test) ,5)) 


This  will  pick  up  the  word  State  from  the  string  Empire  State  building. 


TABTO(  <  expN  >  ) 

This  function  moves  over  to  the  specified  column  <  expN  >  for  just  the  cur¬ 
rent  line  before  continuing  output.  A  negative  argument  sets  TABTO  to  0.  As 
with  LMARGQ,  0  and  1  are  equivalent. 


NOTE 

Space  characters  (ASCII  32)  are  inserted.  The  actual  tab  character  is 
not  used. 


Usage 

You  can  use  this  function  for  formatting  the  text  of  the  output  file.  For  exam¬ 
ple,  you  may  want  all  code  comments  to  begin  in  the  same  place. 


Example 


Load  menu.bin{TABT0(40)}&&  A  binary  program 
for  menu  support. 


This  will  print  the  comment  at  column  40. 


TEXTCLOSE() 

This  function  closes  a  file  opened  by  TEXTOPENQ.  Files  are  automatically 
closed  by  subsequent  TEXTOPENQ  requests  or  upon  the  end  of  a  template. 


Usage 

You  should  try  to  close  text  files  when  not  in  use  to  reduce  some  processing 
overhead. 
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JOBNAME  No  Job  Name  PACE:  28  SESS:  8  OUTPUT:  Fn  Jul  29  21:29:53  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpchap5 


Example 

(INCLUDE  "Builtin.def  ;  ENUM  eof  =  -1;  VAR  open,  temp,  crlf,  line;  line  =  0; 
crlf  =  CHR(13)+(CHR( 10) ) ;  open  =  TEXT0PEN( "myfile.doc") ; 

IF  open  THEN  temp  =  "a"; 

DO  temp  =  TEXTGETLO;  WHILE  temp  !=  eof 

CPUT(temp);  CPUT(crlf);  line  =  1 ine+(LEN(temp)/79+I) 

IF  line  >  21  THEN  PAUSECTIore. . . ") ;  line  =  0;  CLSO;  ENDIF 
ENDDO 
ENDIF 

TEXTCLOSE  ( ) ;  PAUSECPress  a  key...") 

RETURN  0;> 


This  program  opens  a  file  called  Myfile.doc  and  displays  the  first  21  lines  of 
text  on  the  screen.  Lines  longer  than  80  characters  should  be  word  wrapped 
by  the  monitor  hardware.  The  division  by  79  is  to  keep  track  of  the  number 
of  lines  printed  on  the  monitor.  Once  21  lines  are  written  the  template 
pauses  and  displays,  More....  Any  key  pressed  clears  the  screen  and  displays 
the  next  2 1  lines  of  text.  This  is  repeated  until  the  EOF  character  is  read. 


TEXTGETC() 

This  function  returns  a  character  from  the  current  position  of  the  open  text 
file. 


Usage 

The  file  position  is  advanced  by  one  character.  When  the  end  of  file  is 
encountered,  —  1  is  returned  bv  the  function.  The  end  of  file  may  be  a  Ctrl-Z 
(ASCII  26)  or  the  physical  end  of  the  file. 


Example 


(ENUM  eof  =  -1;  VAR  open,  temp; 
open  =  TEXT0PEN( "myfile.doc"); 

IF  open  THEN  temp  *  "a"; 

DO  temp  =■  TEXTGETCO ;  WHILE  temp  !=  eof 
temp  -  TEXTGETCO; 

END00 

ENDIF 

|  TEXTCLOSE! );) 

This  reads  one  character  at  a  time  out  of  the  file  Myfile.doc. 


TEXTGETLO 

This  function  returns  a  line  from  the  current  position  of  the  open  text  file. 
The  line  may  be  up  to  254  characters  long.  Line-end  characters  and  CRLFs 
are  removed.  In  a  line  longer  than  254  characters,  the  first  254  are  returned 
and  the  position  is  set  to  the  first  character  of  the  remainder  of  the  line. 
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JOBNAME:  No  Job  Name  PAGE:  29  SESS:  8  OUTPUT:  Fri  Jul  29  21:29:53  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpchapS 


Usage 

The  file  position  is  advanced  to  the  first  character  past  the  end  of  line.  When 
the  end  of  file  is  encountered,  —  1  is  returned  by  the  function.  The  end  of 
file  may  be  a  Ctrl-Z  (ASCII  26)  or  the  physical  end  of  the  file. 

Example 


(INCLUDE  "Builtin.def";  ENUM  eof  -  -I;  VAR  open,  temp,  crlf,  line;  line  =  0; 
crlf  =  CHR(13)+(CHR(10));  open  =  TEXTOPENC'myfi le.doc" ) ; 

IF  open  THEN  temp  =  "a"; 

DO  temp  =  TEXTGETLO;  WHILE  temp  !=  eof 

CPUT(temp);  CPUT(crlf);  line  =  line+(LEN(temp)/79+l) 

IF  line  >  21  THEN  PAUSE  ("More. ;  line  =  0;  CLSO;  ENDIF 
ENDDO 
ENDIF 

TEXTCLOSEO;  PAUSEC'Press  a  key...") 

RETURN  0;) 


This  template  gets  one  line  at  a  time  out  of  the  Myfile.doc  file.  See 
TEXTCLOSEO  for  further  discussion. 


TEXTGPOSO 

This  function  returns  the  current  file  position  of  the  open  text  file. 


Usage 

The  file  position  is  a  number  where  0  is  the  first  character  in  the  file.  If  no 
file  is  open,  0  is  also  returned. 


Example 


(ENUM  eof  ■=  -1;  VAR  open,  temp,  linepos; 

|  open  *  TEXTOPENC'myfi  le.doc1'); 

IF  open  THEN  temp  =■  "a"; 

DO  temp  -  TEXTGETLO ;WHILE  temp  !=  eof 
\linepos  -  textgposO; 

CPUT(temp);  CPUT( "Posi t i on  ="  +  STR(linepos) ;) 
I  EN0D0 
!  ENDIF 

i  TEXTCLOSEO;) 


The  function  TEXTGPOS( )  displays  the  current  position  in  the  Myfile.doc 
file. 
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JOBNAME:  \'o  Job  Same  PAGE:  30  SESS:  7  OUTPUT:  Fri  Jul  29  21:29:53  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpchapS 


TEXTOPEN() 

This  function  opens  and  initializes  a  text  file  for  input.  The  file  position  is  set 
to  the  start  of  the  file.  If  the  file  is  successfully  opened,  a  1  (true)  is  returned. 
If  the  file  could  not  be  opened,  a  0  (false)  is  returned. 


Usage 

If  a  file  is  open  and  a  subsequent  TEXTOPEN( )  is  issued,  the  previously 
opened  file  is  closed. 


Example 


(ENUM  eof  =  -1;  VAR  open,  temp,; 
open  =  TEXTOPENI "myfile.doc") ; 

IF  open  THEN  temp  =  "a"; 

00  temp  =  TEXTGETLO;  WHILE  temp  !=  eof 
CPUT(temp) ; 

END00 

ENDIF 

TEXTCLOSEO ;) 


Here  TEXTOPENQ  opens  a  file  called  Myfile.doc.  If  the  file  is  successfully 
opened,  the  DO  WHILE  loop  is  executed. 


TEXTSPOS(  <  expN  >  ) 

This  function  sets  the  file  position  in  the  text  file  to  the  number  specified. 
The  position  specified  should  be  a  non-negative  number. 


Usage 

Use  0  to  reset  the  file  position  to  the  start  of  the  file.  A  position  past  the  end 
of  the  file  sets  the  file  position  to  the  end  of  the  file. 


Example 


(ENUM  eof  =  -1;  VAR  open,  temp,  linepos; 
open  =  TEXT0PEN( "myfile.doc");  TEXTSPOS (80*3 ) ; 

IF  open  THEN  temp  ■  "a"; 

DO  temp  =  TEXTGETLO;  WHILE  temp  !=  eof 

CPUT(temp);  CPUT < "Posi t i on  =  "+  STR(linepos);) 
ENDDO 
ENDIF 

TEXTCLOSEO;) 


This  example  uses  TEXTSPOS( )  to  position  on  line  4  of  a  text  file  in  order  to 
skip  a  text  file  header  and  begin  processing  the  relevent  data. 
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JOBNAME:  No  Job  Name  PAGE:  31  SESS:  7  OUTPUT:  Fri  Jul  29  21:29:53  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpchap5 


TYPEC(  <  cursor  >  ) 

This  function  returns  a  number  indicating  the  type  of  the  value  of  the 
attribute  currently  pointed  to  by  the  cursor.  The  returned  values  are: 

1  =  number 

2  =  string 

3  =  element 

4  =  object 

5  =  dosfile 


Usage 

This  allows  you  to  determine  the  type  of  a  specific  attribute. 


Example 


(FOREACH  ATTRIBUTE  k  } 

attribute  (k)  is  iid  UIDC(k) )  with  a  value  of  (VALC(k)} 
of  type  {TYPEC(k)) 

(NEXT  k;} 


The  type  number  of  the  attribute  value  will  be  output. 


UPPER(  <  expC  > ) 

This  function  converts  a  string  to  upper  case. 


Usage 

This  is  useful  for  ensuring  the  uniformity  of  user  input. 


Example 


(VAR  app.name; 
name-"menu.prg" 
app-UPPER(name)) 


The  App  variable  will  hold  MENU.PRG,  even  though  the  original  entry  was 
in  lower  case. 


VAL(  <  expC  > ) 

This  function  converts  a  character  number  to  its  numeric  equivalent. 
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JOBNAME:  N'o  Job  Name  PAGE:  32  SESS:  7  OUTPUT:  Fri  Jul  29  21:29:53  1988 
CLS:  manhai  GRP:  manhat  JOB:  mantmplan  DIV:  tmpchapS 


Usage 

This  is  useful  if  you  need  to  do  arithmetic  operations.  You  may,  for  example, 
want  to  keep  an  internal  documentation  number. 


Example 


(VAR  string,  num; 
string="3"; 
num=VAL(string) ; 
num=num+l> 


This  results  in  the  Num  variable  holding  4,  the  value  of  the  String  variable 
plus  1. 


VALC(  <  cursor  >  ) 

This  function  returns  the  actual  value  of  the  attribute  pointed  to  by  the  cur¬ 
sor.  The  returned  value  may  be  a  number  or  a  string. 


NOTE 

The  value  must  be  printable  to  be  accessible.  It  must  be  an  attribute, 
not  an  element  or  object. 


Usage 

This  allows  you  to  determine  the  value  of  a  specific  attribute. 


Example 


(FOREACH  ATTRIBUTE  k  > 

attribute  (k)  is  i id  (I!DC(k)}  with  a  value  of  (VALC(k)} 
of  type  (TYPEC(k)} 

(NEXT  k;) 


VERSION*) 

This  function  returns  the  generator  version  number. 


Usage 

This  is  helpful  in  documenting  the  version  of  the  Applications  Generator 
used. 
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JOBNAME:  No  Job  Name  PAGE:  33  SESS:  7  OUTPUT:  Fri  Jul  29  21:29:53  1988 
CLS.  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpchapS 


Example 

Application  Documentation  Date:  (DATEO) 
Created  using  Generator  Version:  (VERSION ( ) } 
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JOBNAME:  No  Job  Name  PAGE:  1  SESS:  6  OUTPUT:  Fri  Aug  5  00:02:44  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpsecdiv3 


Template  Language 


The  Template 
Compiler  and 
Interpreter 

6.  Creating  Templates 


JOBNAME:  No  Job  Name  PAGE:  2  SESS:  4  OUTPUT:  Fri  Aug  5  00:02:44  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpsecdiv3 


m 


JOBNAME:  No  Job  Name  PAGE:  I  SESS:  10  OUTPUT:  Mon  Jul  25  1  1:09:26  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpchap6 


Creating 

Templates 


The  process  of  creating  a  working  template  in  the  Template  Language 
involves  the  use  of  a  standard  text  editor,  the  compiler  (Dtc.exe),  and  the 
interpreter  (Dgen.exe).  This  chapter  provides  the  details  of  using  the  Tem¬ 
plate  Language  compiler  and  interpreter. 

A  standard  development  sequence  would  be  to  write  the  template,  compile 
it  using  Dtc.exe,  and  then  test  it  using  the  stand-alone  interpreter  Dgen.exe. 
The  interpreter  provides  a  debugger  that  can  be  invoked  by  functions  within 
your  template  or  by  command  line  switches. 


The  Template  Language  Compiler 

The  compiler  is  a  stand-alone  program  named  Dtc.exe.  Template  source  files 
have  the  .cod  extension.  These  are  the  input  files  for  the  compiler.  The  com¬ 
piled  Dtc.exe  output  file  has  the  .gen  extension. 

The  compiler  processes  the  original  input  file  and  any  files  INCLUDEd  by  the 
main  input  file.  Dtc.exe  is  invoked  using  command  line  option  arguments. 


Command  Syntax 

DTC  [arguments] 

Arguments  are  signaled  by  a  hyphen  followed  by  the  argument  name:  a 
single  lower-case  alphabetic  character.  Unless  otherwise  specified,  the  space 
between  the  argument  and  its  string  is  optional.  For  example,  dtc  -i  myprog 
and  dtc  -imyprog  are  both  acceptable.  Paths  are  supported. 

-i  <  filename  > 

The  specified  file  assumes  the  source  input  is  to  be  compiled. 

-o  <  filename  > 

The  specified  file  receives  the  compiled  output.  The  dot  extension  must  be 
specified. 

Although  many  source  files  may  be  incorporated  into  a  single  compilation 
through  the  INCLUDE  command  within  the  template,  only  one  object  file  is 
created. 
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JOBNAME:  No  Job  Name  PAGE:  2  SESS:  11  OUTPUT:  Thu  Aug  11  14:53:12  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpchap6 


If  -o  is  not  specified,  a  file  named  <  input  filename  >  .gen  is  created  in  the 
current  directory. 

-I  <  filename  > 

A  list  of  the  source  lines  read  with  line  numbers  is  written  to  the  specified 
file.  If  you  do  not  specify  A  fhe  output  goes  to  the  console. 


NOTE 

The  compiler  directives  to  control  the  output  to  <  filename  >  are 
ttcodon,  ncodoff,  Alston,  and  *tlstoff. 


-a 

This  includes  assembly  listings  with  the  source  lines  in  the  listing  output  file. 


The  Template  Language  Interpreter 

The  stand-alone  interpreter,  Dgen.exe,  is  similar  in  all  respects  to  the  version 
used  by  dBASE  IV  with  the  addition  of  some  debugging  features.  Template 
interpreter  input  files  are  the  .gen  output  of  Dtc.exe.  The  debug  features 
are  invoked  using  functions  within  the  template  and  by  command  line 
arguments. 

Command  Syntax 

DGEN  [arguments] 

Arguments  are  signaled  by  a  hyphen  followed  by  the  argument  name:  a 
single  lower-case  alphabetic  character. 

-t  <  compiled  filename  > 

This  is  the  name  of  the  compiled  template  you  wish  to  process.  It  is  the  -o 
file  of  DTC  and  is  required. 

-i  <  object  files  > 

These  are  the  design  object  files.  This  entry  is  not  required. 

You  may  specify  none,  a  single  file  or  a  group  of  files.  To  specify  a  group 
of  files,  use  the  form  *.app  or  use  a  comma-separated  list,  such  as 
*.app*.pop,*.bar. 


be  created  using  the  DOS  environment  variable  DTL— TRANSLATE. 
This  .npi  file  is  then  used  for  - 1  <  object  files  >  . 


NOTE 

Applications  Generator  design  object  files  may  be  used  directly.  Forms, 
reports,  and  labels  design  object  files  that  can  be  used  by  dGEN  must 


6-2 


CREATING  TEMPLATES 


JOBNAME:  No  Job  Name  PAGE:  3  SESS:  10  OUTPUT:  Mon  Jul  25  11:09:26  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpchap6 


-I  <  list  file  > 

This  is  an  optional  file  to  receive  diagnostic  listing  information  from  the 
debugger. 


-n 

This  is  an  optional  switch -to  turn  echoing  of  the  command  line  arguments 
on. 


DOS  Environment  Variables 


Table  6-1  DOS  environment  variables 


Variable 


Description 


SET  DTI _ TRANSLATE 

=  on 


SET  DTL—NOGEN 
=  on 


Tells  dBASE  to  create  an  additional  source  file 
with  the  extension  .npi  when  reports,  forms,  or 
labels  generators  are  used.  The  .npi  files  can  then 
be  used  with  the  -i  option  of  dGEN. 

Suppresses  dBASE  code  generation.  This  is  mainly 

used  with  DTI _ TRANSLATE  in  order  to  create 

new  design  object  files  without  generating  dBASE 
code. 


SET  DTL_TRACE 
=  on 


This  will  display  all  the  elements  and  attributes  of 
a  design  object  except  for  frame  level  attributes. 
Look  at  a  .def  file  under  Frame  level  selectors  for 
the  list  of  frame  level  attributes. 


The  Debugger 

The  debugger  is  called  from  within  a  template  through  the  functions 
DEBUG()  or  BREAKPOINT! ). 

DEBUG(  <  expN  >  ) 

This  function  turns  on  the  debugger  within  Dgen.exe  at  a  specified  level  of 
diagnostics.  The  level  is  a  number  from  0  to  6.  Levels  above  0  are  ignored 
by  the  dBASE  IV  interpreter. 

0  =  Off. 

1  =  Display  the  generated  text  on  the  screen. 

2  =  Display  the  generated  text  and  monitor  the  keyboard.  The  keyboard  is 

monitored  for  input  of  a  new  level  number  between  0  and  6. 

3  =  Display  generated  text  and  the  operated-on  template  commands,  and 

monitor  the  keyboard. 
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JOBN'AME:  So  Job  Name  PAGE:  4  SESS:  9  OUTPUT:  Fri  Jul  29  21:32:33  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpchapb 

4  =  The  same  as  3  except  that  you  may  single-step  the  template  commands. 

5  =  The  same  as  3,  but  also  trace  stack  and  assembly  code. 

6  =  The  same  as  4,  but  also  trace  stack  and  assembly  code  and  single  step 

on  assembly  instructions  rather  than  source  lines. 


NOTE 

At  levels  3  through  6,  the  operated-on  template  commands  are  sent  to 
the  list  file  specified  by  the  -l  switch  in  Dgen.exe. 


BREAKPOINT^  <  expC  >  ) 

The  specified  message  <  expC  >  is  displayed  on  the  prompt  line  and  the 
user  is  asked  to  enter  a  new  debug  trace  level  from  0  to  6.  If  -1  is  specified 
in  Dgen.exe,  the  breakpoint  message  will  be  written  to  the  list  file. 
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JOBNAME:  No  Job  Name  PAGE:  1  SESS:  6  OUTPUT:  Fri  Aug  5  00:02:54  1988 
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JOBNAME:  No  Job  Name  PAGE:  2  SESS:  4  OUTPUT:  Fri  Aug  5  00:02:54  1988 
CLS:  manhat  GRP'  manhaf  IOR'  mantmnlan  DfV-  tmn«;prHiv4 
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JOBNAME:  No  Job  Name  PAGE:  1  SESS:  6  OUTPUT:  Fri  Jul  29  21:31:52  1988 
CLS:  manhat  GRP:  manhat  JOB:  mantmplan  DIV:  tmpappa 

Template 
Compiler  Error 
Messages 


The  template  compiler  error  messages  are  sent  to  the  screen.  Use  the  DOS 
redirection  command  (  >  )  if  you  wish  to  send  them  to  the  printer  or  a  file. 
The  messages  take  the  following  form: 

<  infile  > 

<  line  number  >  :  <  suspect  code  line  > 

—  >  'word  causing  error7 

Error  <  #  >  :  Error  message 

101  String  constant  expected  after  INCLUDE  keyword 

Correct  form  is  {include  "abc.xyz";}.  Filename  must  be  in  quotes. 

102  Include  file  7  <  filename  >  7  not  found 

No  file  by  the  specified  name  exists.  The  default  path  is  the  one  current 
when  DTC  was  invoked. 

103  Access  violation  error  trying  to  include  file  7  <  filename  >  7 

This  could  occur  if  the  specified  file  is  a  directory  or  on  a  network  with  read 
access  denied,  an  operating  system  besides  DOS,  or  DOS  with  file  sharing 
turned  on. 

104  Error  condition  trying  to  include  file  7  <  filename  >  7 

The  compiler  received  an  unexpected  DOS  error  while  trying  to  do  an 
INCLUDE.  Experiment  with  renaming  or  combining  files,  or  put  them  on 
another  drive. 

105  Too  many  INCLUDES  (trying  to  include  file  7  <  filename  >  ') 

The  compiler  ran  out  of  table  space.  Combine  into  fewer  files. 

106  Duplicate  variable  declaration 

A  variable  was  named  twice  —  the  same  variable  was  declared  twice  in  the 
same  context,  that  is,  globally  or  locally.  Or,  a  local  variable  in  a  function 
has  the  same  name  as  one  of  the  argument  variables. 

107  Comma  expected  at  this  point  in  a  variable  declaration 

The  correct  form  is  {VAR  a,  b}  not  {VAR  a  b}.  Compilation  continues  with  the 
missing  comma  assumed. 

108  Unexpected  termination  of  a  variable  declaration 

A  token  other  than  a  comma,  semicolon,  identifier,  or  right  brace  was 
encountered  in  a  variable  declaration,  for  example,  {VAR  a.  b.ENDIF}.  The 
compiler  terminates  the  variable  declaration  and  attempts  to  use  the  token 
as  part  of  a  statement. 
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109  Duplicate  selector  declared 

The  same  selector  was  declared  more  than  once.  Two  different  selectors 
can  have  the  same  value,  but  cannot  have  the  same  name.  For  example,  the 
second  occurrence  of  field  in  the  following  would  cause  an  error  message: 
{SELECTORS  field  1.  text  2,  field  1;}. 

110  Prospective  selector  name  is  already  In  use 

An  identifier  is  already  in  use  as  something  other  than  a  selector,  such  as  a 
variable  name,  function  name,  or  label.  Example: 

(VAR  moveleft,  movecount; 

SELECTORS  xyz  2,  moveleft  29  //'moveleft'  is  already  in  use 
//  as  a  variable.) 


111  Selector  definition  expected 

A  selector  definition  consists  of  an  identifier  followed  by  number.  A  number 
is  expected  following  the  SELECTORS  keyword.  If  a  comma  follows  a  defini¬ 
tion,  another  keyword  plus  definition  is  expected.  Anything  else  causes  this 
message  to  appear,  and  the  extraneous  tokens  are  skipped  over. 

112  Selector  number  expected  here 

The  number  expected  as  the  second  half  of  a  selector  definition  is  missing. 

113  Comma  expected  at  this  point  in  a  selector  declaration 

The  comma  used  to  separate  selector  definitions  is  missing,  for  example, 
{SELECTORS  a  1  b  2}  instead  of  {SELECTORS  a  1,  b  2}.  Compilation  con¬ 
tinues,  with  the  missing  comma  assumed. 

114  Unexpected  termination  of  a  selector  declaration 

After  a  selector  definition  (identifier  followed  by  number),  a  comma,  semi¬ 
colon,  or  right  brace  is  expected. 

115  Keyword  THEN  inserted  here 

The  keyword  THEN  is  expected  at  this  point  and  is  inserted  just  before  the 
current  token. 

116  Keyword  ELSE  Inserted  here 

The  keyword  ELSE  is  expected  at  this  point  and  is  inserted  just  before  the 
current  token. 

117  Target  label  expected  after  THEN  GOTO  or  ELSE  GOTO 

There  is  no  destination  specified  for  the  GOTO.  The  GOTO  is  ignored,  and 
the  compiler  attempts  to  continue  parsing  with  the  current  token.  For  exam¬ 
ple,  {IF  a  <  b  THEN  GOTO  —  20}  is  treated  as  if  it  were  {IF  a  <  b  THEN 
-20}. 

118  Expression  required  following  IF 

There  must  be  an  expression  between  the  IF  and  THEN  keywords. 

119  IF  statement  terminated 

Normally  an  IF  statement  is  terminated  by  a  corresponding  ENDIF.  How¬ 
ever,  tokens  that  normally  terminate  other  constructs,  (such  as  NEXT,  or 
ENDCASE,  or  end  of  input,  if  not  part  of  a  corresponding  FOREACH  or 
CASE.. .OF  nested  within  the  IF  statement)  cause  the  open  IF  statement 
to  be  terminated.  In  the  example  (CASE  x  OF... IF  a  <  b  THEN  c*d 
ENDCASE),  the  compiler  terminates  the  IF  statement,  on  the  assumption 
that  the  ENDCASE  probably  matches  some  preceding  CASE.. .OF.  Even  if  this 
assumption  is  not  true,  the  IF  statement  is  terminated. 
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120  This  IF  statement  needs  to  return  a  value 

This  message  appears  when  an  IF  statement  follows  a  binary  operator  but 
does  not  yield  a  value.  Since  ELSE  is  missing  from  the  IF  statement  in  the 
following  example,  there  is  no  value  to  take  part  in  the  addition: 

{a  =  250  +  IF  b  <  c  THEN  50  ENDIF}. 

121  DO  statement  terminated 

Normally  a  DO  statement  is.terminated  by  a  corresponding  ENDDO.  How¬ 
ever,  tokens  that  normally  terminate  other  constructs  (such  as  ENDIF, 
ENDCASE,  or  end  of  input,  if  not  part  of  a  corresponding  IF  or  CASE. ..OF 
nested  within  the  DO  statement)  cause  the  pending  DO  statement  to  be  ter¬ 
minated.  In  the  example  {CASE  x  OF.. .DO  PRINT(xyz)  ENDCASE),  the  com¬ 
piler  terminates  the  DO  statement  on  the  assumption  that  the  ENDCASE 
matches  some  preceding  CASE. ..OF.  Even  if  this  assumption  is  not  true,  the 
DO  statement  is  terminated. 

122  Variable  name  required  following  FOR 

The  FOR  keyword  must  be  followed  by  an  existing  variable  name  or  a  name 
that  would  be  allowed  as  a  variable  (that  is,  one  that  starts  with  a  letter,  and 
is  not  already  in  use  as  a  selector). 

123  Bad  or  missing  TO  expression 

The  TO  keyword,  used  in  the  FOR  loop  header,  must  be  followed  by  an 
expression. 

124  Bad  or  missing  STEP  expression 

The  STEP  keyword,  used  in  the  FOR  loop  header,  must  be  followed  by  an 
expression. 

125  FOR  statement  terminated 

Normally  a  FOR  statement  is  terminated  by  a  corresponding  NEXT.  How¬ 
ever.  tokens  that  normally  terminate  other  constructs  (such  as  ENDIF, 
ENDCASE,  or  end  of  input,  if  not  part  of  a  corresponding  IF  or  CASE. ..OF 
nested  within  the  FOR  statement)  cause  the  open  FOR  statement  to  be  ter¬ 
minated.  In  the  example  {CASE  x  OF.. .FOR  xvz=  1  TO  20;  PRINT(xyz) 
ENDCASE),  the  compiler  terminates  the  FOR  statement  on  the  assumption 
that  the  ENDCASE  probably  matches  some  preceding  CASE... OF.  Even  if  this 
assumption  is  not  true,  the  FOR  statement  is  terminated. 

126  Selectors  'makec'  and  'eoc'  required  before  using  FOREACH 

The  FOREACH  loop  creates  a  cursor  and  advances  it  through  a  list  of  items 
by  using  function  calls  to  MAKEC  and  EOC.  The  standard  built-in  definitions 
file,  which  is  usually  INCLUDEd  at  the  beginning  of  a  template,  defines  these 
selectors  for  you. 
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127  Selector  or  value-yielding  expression  required  following  FOREACH 

The  FOREACH  keyword  must  be  followed  by  a  selector  or  an  expression 
returning  a  value.  For  example: 

{FOREACH  IF  a  THEN  b  ENDIF} 

The  IF  statement  does  not  vield  a  value 

{FOREACH}  {FOREACH  IN} 

No  expression  supplied  at  all.* 

{FOREACH  xyz) 

{FOREACH  xvz  p} 

{FOREACH  xyz  p  IN  q} 

These  are  all  correct  syntax. 

128  Expression  required  after  IN 

If  the  IN  keyword  is  used  in  a  FOREACH  statement,  an  expression,  usually 
a  variable  name,  must  follow  the  IN.  For  example,  {FOREACH  xyz  IN}  does 
not  have  an  expression  following  the  IN.  {FOREACH  xyz  IN  p}  is  the  correct 
syntax. 

129  FOREACH  statement  terminated 

Normally  a  FOREACH  statement  is  terminated  by  a  corresponding  NEXT. 
However,  tokens  that  normally  terminate  other  constructs  (such  as  ENDIF, 
ENDCASE,  or  end  of  input,  if  not  part  of  a  corresponding  IF  or  CASE.. .OF 
nested  within  the  FOREACH  statement)  cause  the  open  FOREACH  statement 
to  be  terminated.  In  the  example  {CASE  x  OF.. .FOREACH  xyz;  PRINT(xyz) 
ENDCASE},  the  compiler  terminates  the  FOREACH  statement  on  the  assump¬ 
tion  that  the  ENDCASE  probably  matches  some  preceding  CASE... OF.  Even  if 
this  assumption  is  no:  true,  the  FOREACH  statement  is  terminated. 

130  NEXT  variable  mismatch  —  loop  header  is: 

An  optional  variable  name  may  be  supplied  following  the  NEXT  keyword. 

If  it  is  supplied,  it  is  checked  to  see  that  it  matches  the  variable  used  in  the 
header  of  the  loop. 

131  Not  inside  any  loop  currently 

WHILE,  UNTIL,  LOOP,  and  EXIT  all  have  no  meaning  outside  of  a  DO,  FOR, 
or  FOREACH  loop. 

132  Expression  required  following  WHILE  or  UNTIL 

A  value-yielding  expression  must  follow  the  WHILE  or  UNTIL  keywords.  For 
example,  {WHILE  a>bB}  is  correct;  {WHILE  GOTO  xyz}  is  incorrect. 

133  Overriding  previous  definition  of '  <  identifier  >  ' 

The  ENUM  statement  allows  you  to  define  a  given  identifier  as  a  synonym  for 
a  previously  defined  symbol.  The  identifier  assigned  is  already  being  used  for 
a  variable  name,  user-defined  function,  label,  or  other  attribute.  The  assign¬ 
ment  in  the  ENUM  statement  takes  precedence  over  the  previous  meaning  of 
the  identifier.  This  message  is  not  given  if  the  only  previous  use  of  the  identi¬ 
fier  was  in  ENUM  statements. 

134  Erroneous  expression  In  ENUM 

When  an  ENUM  statement  sets  an  identifier  to  be  a  synonym  to  a  value  that 
is  an  expression  rather  than  a  single  token,  the  expression  must  contain  only 
numeric  constants  or  symbols  ENUMed  to  constants.  For  example,  in 
{ENUM  xyz  =  49-1-  'abc';},  'abc'  is  not  a  numeric  constant. 
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135  Value-yielding  expression  required  between  CASE  and  OF 

You  must  specify  an  expression  between  CASE  and  OF  that  returns  a  value. 

136  This  CASE. ..ENDCASE  construct  has  no  case  instances  in  it 

There  must  be  at  least  one  CASE  instance  between  OF  and  ENDCASE. 

137  Case  instances  must  be  inside  a  CASE.. .ENDCASE  construct 

A  construct  like  CASE  25  that  occurs  outside  a  CASE.. .ENDCASE  statement 
would  trigger  this  message.' 

138  Duplicate  case  instance 

You  used  the  same  CASE  constant  in  two  different  CASEs  within  the  same 
construct,  for  example,  {CASE  a  of  1:  'xyz';  1:  'abc'  ENDCASE}. 

139  Variable  used  in  a  case  instance  -  constant  required 

The  CASE  instance  you  have  named  has  not  been  defined  as  a  constant.  The 
CASE. ..ENDCASE  construct  provides  an  efficient  way  to  match  the  value  of 
the  selection  expression  against  a  list  of  constants,  and  to  jump  directly  to 
the  appropriate  code  for  that  case.  This  is  easier  to  read,  and  executes  faster 
than  a  series  of  IF...ENDIF  statements.  To  compare  the  selection  expression 
against  a  list  of  other  expressions  with  values  that  will  not  be  known  until 
run  time,  use  a  series  of  IF...ENDIF  statements. 

140  Syntax  error  in  CASE  selection  expression 

The  CASE... OF  construct  expects  a  single  value-yielding  expression  between 
CASE  and  OF.  Any  punctuation  or  keywords  that  are  not  part  of  a  valid 
expression  will  result  in  this  message.  For  example,  {  CASE  NEXT  }  has 
an  inappropriate  keyword,  and  {  CASE  ;  }  has  an  inappropriate  semicolon. 

{  CASE  2*myfunc(x,y)  OF  }  is  a  valid  expression. 

141  Duplicate  user-defined  function  name 

A  user-defined  function  of  the  given  name  has  already  been  defined.  The 
new  definition  will  be  compiled  normally,  but  any  calls  will  go  to  the  origi¬ 
nal  definition. 

142  Nested  function  definition 

Function  definitions  cannot  be  nested. 

143  Missing  name  in  function  definition 

The  DEFINE  keyword  was  not  followed  by  an  identifier.  Compilation  will 
continue  as  if  the  DEFINE  keyword  had  not  been  seen;  this  may  result  in 
more  error  messages. 

144  Comma  expected  in  parameter  list,  inserted 

A  comma  was  missing  in  a  parameter  list.  For  example,  {DEFINE  x(a  b)}  was 
used  instead  of  {DEFINE  x(a,b)}.  The  parser  assumes  the  comma  and  contin¬ 
ues  parsing. 

145  Function  definition  parameter  list  terminated  by  unexpected  token 

The  parameter  list  should  be  a  list  of  identifiers  separated  by  commas,  and 
terminated  by  a  right  parenthesis.  Any  other  token  terminates  the  parameter 
list. 

146  Function  call  construct  terminated 

Function  call  arguments  are  separated  by  commas,  and  end  with  a  right 
parenthesis.  A  token  that  does  not  belong  to  the  current  expression  in  the 
list,  and  that  is  not  a  comma  or  a  right  parenthesis,  causes  this  error.  In  the 
example  {a  =  myfunc(2*b  THEN);),  the  THEN  would  cause  this  error. 
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147  Selector  expected  following 

This  results  from  any  token  except  a  selector  following  the  operator. 
Compilation  continues  as  if  the  were  not  present. 

148  Dot  not  allowed  following  constant,  deleted 

The  dot  is  only  used  following  a  cursor  to  select  an  item  from  a  list.  Numeric 
constants  must  be  integers;  there  is  no  decimal  point. 

149  Variable  unknown 

You  used  an  identifier  as  if  it  were  a  variable  name,  but  there  was  no  decla¬ 
ration  of  that  identifier  as  a  variable.  Note  that  if  a  variable  is  declared  inside 
a  function  definition,  it  disappears  as  soon  as  the  ENDDEF  for  that  function 
is  processed. 

150  Terminating  string  delimiter  missing 

Example:  {  a  =  "There’s  no  quote  on  the  end  of  this  string  ...} 

151  Unexpected  token;  skipped 

The  current  token  does  not  fit  any  current  or  pending  constructs,  and  does 
not  start  a  new  one.  Example: 

{VAR  a,b,c; 
a  =  b  +  NEXT} 

If  no  FOREACH  construct  is  open,  the  NEXT  is  out  of  place. 

{if  a  =  =  b  ;  then} 

The  semicolon  is  out  of  place  inside  an  IF  condition. 

152  Empty  parentheses 

A  pair  of  parentheses  contains  no  value-yielding  expression,  for  example, 

{a  =  b  +  ()  +  c}. 

153  Terminating  open  left  parenthesis 

A  corresponding  closing  right  parenthesis  was  not  encountered  before  one  of 
the  following:  a  right  brace,  INCLUDE,  THEN,  ELSE,  or  ENDIF  keyword, 
end  of  file,  end  of  input,  or  semicolon.  The  opening  left  parenthesis  is  con¬ 
sidered  closed.  Examples: 

{a  =  b*(c  +  d;  }  Semicolon  before  closing  right  parenthesis 
{a  =  b/(c*d}  Missing  right  parenthesis 

154  No  pending  left  parenthesis 

A  right  parenthesis  was  encountered  with  no  corresponding  left  parenthesis 
open.  Example:  {a  =  b  );  } 

155  Duplicate  label  definition 

The  same  name  is  used  as  a  label  in  two  different  places.  The  first  definition 
has  precedence. 

156  Bad  target  of  GOTO;  skipped 

The  GOTO  keyword  should  be  followed  by  an  identifier  which  cannot  be  a 
selector.  The  GOTO  is  ignored. 

157  Missing  operand 

The  construct  to  the  left  of  a  binary  operator  does  not  yield  a  value.  The 
compiler  substitutes  a  zero  for  the  missing  operand. 
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158  Operator  deleted 

This  is  caused  by  an  operator  with  no  operand  or  by  a  binary  operator  fol¬ 
lowing  another  binary  operator.  The  star  is  deleted  by  the  compiler  in  the 
following  examples: 

(  a  =  b*  }  No  operand  following  the  star 

{  a  =  b  +  *  c  }  The  star  follows  plus,  which  is  a  binary  operator  here 

159  Post-increment/decrejnent  not  supported 

The  '  +  +  '  and  ' — '  operators  can  precede  a  variable  (pre-increment),  but 
cannot  follow  a  variable  (post-increment).  For  example,  in  {  VAR  a,b,c; 
a  =  b  +  +  ;},  the  '  +  +  '  following  the  b  is  illegal. 

160  Requires  lvalue 

You  attempted  to  store  a  value  into  something  other  than  a  variable,  or  into 
an  undeclared  variable.  In  the  example  {  VAR  number;  numbr  =  20;},  the 
misspelled  name  results  in  this  message.  In  {  36  =  29;  ),  the  lack  of  a  vari¬ 
able  results  in  the  message. 

161  Function  never  defined 

A  user-defined  function  call  was  made,  but  no  definition  for  a  function  by 
that  name  was  encountered. 

162  Label  never  defined 

A  GOTO  to  a  specified  label  occurred  somewhere  in  the  function  just  ended, 
but  the  label  was  not  defined  within  the  function.  Or,  a  GOTO  to  a  specified 
label  occurred  somewhere  outside  any  function  definitions  but  the  label  was 
not  defined  at  that  level. 


163  Terminates  open  construct(s): 

An  unmatched  terminating  keyword,  such  as  ENDIF,  was  encountered  while 
an  opening  keyword,  such  as  CASE,  was  pending.  The  compiler  identifies  the 
terminating  keyword,  then  displays  beneath  it  each  opening  keyword  that  is 
terminated. 

164  No  IF  pending;  skipped 

ENDIF  is  seen  when  no  IF  is  pending. 

165  No  CASE  statement  pending;  skipped 

ENDCASE  is  seen  when  no  CASE  is  pending. 

166  No  DO  pending;  skipped 

ENDDO  is  seen  when  no  DO  is  pending. 

167  No  FOR  or  FOREACH  pending;  skipped 

NEXT  is  seen  when  no  FOR  or  FOREACH  is  pending. 

168  No  DEFINE  in  progress;  skipped 

ENDDEF  is  seen  when  no  DEFINE  is  open. 

901-999  (Internal:  <  internal-message  >  ) 

These  numbers  indicate  internal  errors  within  the  compiler.  Try  rearranging 
the  statement  or  expression  that  seems  to  have  caused  the  error,  and  contact 
Ashton-Tate  Software  Support. 
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Introduction 


Language  Reference  is  an  encyclopedia  of  dBASE  IV  commands,  functions,  sys¬ 
tem  variables,  and  system  configuration.  If  you  have  completed  Learning 
dBASE  TV  or  Using  the  Menu  System,  this  manual  is  for  you.  If  you  are  already 
familiar  with  dBASE  programming,  or  database  management,  you  will  find  this 
manual  a  useful  reference  tool. 

If  you  are  an  intermediate-to-advanced  user,  you  may  also  wish  to  refer  to 
Programming  with  dBASE  IV and  the  Sample  Programming  Code  booklet.^ 

This  manual  is  organized  into  six  chapters,  nine  appendixes,  and  an  index: 


Chapter  1 :  Essentials 


This  contains  a  discussion  of  the  dBASE  IV  basic/  using  commands,  SET  corn^.  _ , 

mands,  functions,  memory  variahlegQanrf  tystem  variables.  It  »tee£covers  the  r ABASc. 

/BBASE  command  line,  how  to  use  operators  to  create  expressions,  now  to  cre-\ £-c’‘A<=er 
late  reports  and  labels,  how  to  build  your  own  user-defined  functions,  basic  L^nc)  KO*-j  to 
l  database  file  manipulation,  setting  up  relations  between  files,  and  searching  fo r e 
\lata.  _ — - 


U**v< 


Chapter  2:  Commands 


Chapter  3:  SET  Commands 


This  chapter  provides  an  alphabetical  listing  of  the  commands  you  can  use  in 
the  dBASE  IV  language.  Each  entry  contains  a  basic  syntax  paradigm  and  notes 
on  how  to  use  the  command.  Many  commands  also  contain  tips,  examples,  and 
cross  references  to  other  commands  and  functions. 

The  files  used  in  the  examples  are  listed  in  Appendix  C,  “Sample  Files.” 


These  are  a  subset  of  dBASE  IV  commands,  listed  in  alphabetical  order.  SET 
commands  allow  certain  settings  that  control  how  dBASE  presents  information 
on  the  screen  or  printer,  or  that  establish  an  environment  affecting  the  way 
other  commands  and  functions  operate. 
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Chapter  4:  Functions 

Chapter  4  contains  the  same  type  of  information  for  the  functions  as  Chapter  2 
and  3  contain  for  commands.  Each  function  is  listed  in  alphabetical  order  and 
thoroughly  described.  The  description  includes  a  definition,  syntax,  usage, 
examples,  and  any  tips  that  make  it  easier  for  you  to  use. 


Chapter  5:  System  Variables 

System  variables  are  a  class  of  memory  variables  that  dBASE  IV  reserves  to 
hold  information  about  printing  and  the  format  of  printed  material.  This  chap* 
ter  contains  information  about  tailoring  your  printing  jobs  by  changing  the  val¬ 
ues  of  these  variables. 


Chapter  6:  Customizing  dBASE  IV 

Certain  screen,  printer,  and  memory  parameters  are  initialized  when  you  start 
up  dBASE  IV.  This  chapter  provides  information  on  these  parameters,  and 
explains  how  to  change  the  environment  that  dBASE  initializes  in  memory 
upon  loading. 


Appendixes 

These  are  as  follows: 

A  list  of  error  messages  and  applicable  code  numbers,  along  with  explana¬ 
tions  of  possible  causes  of  the  messages 

dBASE  IV  technical  specifications 

The  sample  files  that  are  used  for  all  examples  in  this  manual 

Keystrokes  that  are  used  in  :he  dBASE  IV  program  editor 
screens _ _ _ _ 

A  summary  of  the  types  of  files  that  dBASE  IV  uses  and  creates,  and  the  file 
extensions  that  are  written  to  disk  when  these  files  are  saved 

Notes  on  the  structure  of  a  database  (  dbf)  and  memo  (  dbt)  file 
A  list  of  available  printer  drivers,  and  the  type  styles  each  supports 

The  ASCII  chart,  which  provides  hexadecimal  and  decimal  equivalents  for 
each  character 

Classification  of  the  functions  according  to  their  use 


Index 
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Essentials 


The  Control  Center  lets  you  easily  use  commands,  SET  commands, 
functions,  and  system  memory  variables  without  knowing  details  of  their 


- - - j - - - 

operation/oecause  it  builds  the  command  line  from  options  you  choose 
from  a  menu  or  from  items  you  enter  on  the  blackboard.  You  may  also  build 


your  own  com  mand  line,  if  you  are  familiar  with  the  dBASE  IV  language 
components. 


About  This  Chapter 


In  this  chapter  you  will  find  the  basic  essentials  needed  to  construct  a 
dBASE  IV  command  line.  A  com  mand  line  is  a  complete  instruction  that 
directs  the  dBASE  IV  processor  to  act  on  data  items,  and  may  contain  a 
command  (or  SET  command),  functions ,  and  system  memory  variables.  You 
can  find  further  information  on  each  of  these,  respectively,  in  chapters  2,  3, 
4,  and  5.  53 

You  may  enter  a  command  line  at  the  dot  prompt,  or  as  part  of  a  program. 


dBASE  IV  Language  Components 


Each  language  component  has  a  role  in  the  command  line: 

■  Commands  are  verbs  that  direct  the  dBASE  processor  to  perform  a  cer¬ 
tain  action.  Although  a  command  line  may  optionally  contain  another 
language  component,  it  must  contain  one  (and  only  one)  command. 
Sometimes  the  command  verb  is  implied  in  the  command  line,  as  with 
the  STORE  command.  The  command  lines: 


1 


'5  TO  x 


J 


are  jhe  same,  but  the  STORE  command  is  implied  in  the  second  form. 
Beciuse  each  command  line  must  contain  a  command  verb,  the  term 


Because  each  command  line  must  contain  a  command  verb,  the  term 
comfnand  line  is  often  simply  referred  to  as  the  command. 
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■  SET  commands  are  a  subset  of  commands  that  usually  set  up  the  envi- 
ronment  in  which  the  processor  acts.  For  example,  SET  COLOR  sets  the 
colors  on  the  screen  and  affects  other  commands  that  output  to  the 
screen. 

■  Functions  work  in  two  ways: 

1.  Some  functions  are  adjectives  or  adverbs  that  modify  a  data  item.  For 
example,  LOWERQ  converts  uppej^ase  letters  to  lowercase. 

2.  Other  functions  hold  a  dBASE  IV  value  or  condition  that  you  can 
query.  The  function  EOF()  will  be  set  to  true  (.T.)  when  you  are  at  the 
end  of  a  database  Hie,  and  the  command: 

?  EDFO 
returns 


.T. 

■  System  memory  variables  are  settings  that  control  the  appearance  of 
printed  and  screen  output.  While  commands,  SET  commands,  and  func- 
tions  were  language  components  in  earlier  versions  of  dBASE  III  and 
dBASE  III  PLUS,  system  memory  variables  are  new  to  dBASE  IV. 

System  memory  variables  are  like  SET  commands  in  that  they  usually 
control  system  parameters  rather  than  act  on  data  items.  They  are  like 
functions  in  that  you  can  query  the  values  they  contain. 

In  this  manual,  commands  are  printed  in  uppepfase,  such  as  LIST.  SET  com¬ 
mands  are  also  uppeijPase,  and  always  begin  with  the  word  SET,  such  as  SET 
DEVICE.  Functions  are  also  printed  in  uppercase,  but  end  with  parentheses, 
such  as  FOUNDQ.  System  memory  variables  are  loweijcase,  and  begin  with 
an  underscore,  such  as  _padvance.  These  conventions  help  you  distinguish 
among  the  terms;  for  example,  CHANGE()  is  a  function,  but  CHANGE  is  a 
com  mand. 


Dot  Prompt  Interface 

dBASE  IV’s  interactive  mode,  which  allows  you  to  enter  a  command  line 
and  get  an  immediate  response,  is  signajfTd  by  a  dot  on  the  screen  and  is 
therefore  known  as  the  dot  prompt.  Using  the  dot  prompt  may  give  you  more 
speed  and  flexibility  than  if  you  work  only  from  the  Control  Center. 

You  issue  a  command  in  dBASE  IV  by  typing  it  at  the  dot  prompt  and  press¬ 
ing  You  must  enter  the  complete  command  on  a  single  line,  to  a  maxi¬ 
mum  of  1024  characters. 

If  you  are  typing  in  a  long  command  line  at  the  dot  prompt,  press  Ctrl-Home 
to  open  an  editing  window  on  the  screen.  When  typing  commands  in  the 
editing  window,  you  have  access  to  all  the  features  of  dBASE  IV’s  text  editor, 
and  you  can  see  the  entire  instruction  without  scrolling  back  and  forth  from 
the  beginning  of  the  command  line  to  the  end. 
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Commands  may  be  abbreviated  to  the  first  four  characters  (except  SOL 
commands).  You  can  abbreviate  REPORT  FORM  to  REPO  FORM  and 
MODIFY  COMMAND  to  MODI  COMM,  for  example,  but  you  must  use  the 
entire  SQL  command. 

You  may  enter  command  lines  in  uppe^fase,  lowercase,  or  a  combination  of 
the  two.  You  may  also  include  any  number  of  blank  spaces  between  the 
words  of  a  command  line.  Each  blank  space,  however,  counts  as  one  charac¬ 
ter  of  the  1024-character  maximum  per  command  line. 


Re-entering  Commands 

The  dot  prompt  has  a  memory  buffer  called  history  that  automatically  stores 
commands  as  you  enter  them.  This  lets  you  go  back  and  edit  or  run  a  previ¬ 
ous  command.  When  you  installed  dBASE  IV,  a  default  of  20  com m ands  was 
set  for  the  history  buffer.  You  can  use  SET  HISTORY  to  change  the  default 
number  of  stored  commands  from  20  to  a  number  from  0  to  16,000.  You  can 
also  reconfigure  the  default  by  changing  your  Config.db  file  (see  Chapter  6, 
“Customizing  dBASE  I\0). 

Press  T  at  the  dot  prompt  to  display  commands  previously  stored  in  the  his¬ 
tory  buffer.  The  commands  appear  one  at  a  time  in  reverse  order,  i  moves 
the  cursor  back  down  the  list  of  commands.  You  can  run  the  stored  com¬ 
mand  when  it  is  at  the  dot  prompt  by  pressing  *♦.  Use  DISPLAY  HISTORY 
and  LIST  HISTORY  to  view  more  than  one  command  at  a  time. 


*/*■ 
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Programs  and  Procedures 

If  you  execute  the  same  series  of  commands  repeatedly,  and  you  want  to 
automate  the  process,  you  may  save  these  instructions  in  a  program  file. 

Programs 

A  program  is  a  sequence  of  dBASE  IV  commands  contained  in  a  disk  file. 
When  you  execute  the  program  file,  the  commands  in  the  program  are  exe¬ 
cuted  as  if  you  had  typed  them  from  the  dot  prompt. 

You  can  use  the  dBASE  IV  program  editor,  which  is  accessed  with  MODIFY 
COMMAND,  to  write  and  save  your  programs.  MODIFY  COMMAND  creates  a 
disk  file  with  a  .prg  extension. 

When  creating  a  program  file,  type  *♦  to  indicate  the  end  of  a  command 
line.  To  continue  a  command  on  several  lines,  type  a  semicolon  at  the  end  of 
each  line  and  after  the  last  line  of  the  command. 

You  can  execute  the  program  file  with  the  DO  command.  Before  executing 
your  program  file,  DO  compiles  the  commands  into  object  code,  which  runs 
much  faster  than  the  original  source  code  in  the  .prg  file,  and  it  writes  the 
object  code  to  a  disk  file  with  a  .dbo  extension.  You  may  also  use  thejCOM- 
PILE  command  to  generate  an  object  file  without  executing  the  program. 
dBASE  IV  notifies  you  of  any  errors  it  encounters  during  compilation. 
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Procedures 

A  program  may  be  composed  of  one  or  more  routines,  called  procedures. 
Each  procedure  usually  does  one  basic  task,  and  can  be  called  from  other 
procedures,  programs,  or  from  the  dot  prompt  with  a  DO  command.  When 
the  procedure  finishes  its  task,  it  returns  control  to  the  program  or  proce¬ 
dure  that  called  it,  or  to  the  dot  prompt. 

In  earlier  versions  of  dBASE,  procedures  were  usually  contained  in  a  sepa¬ 
rate  file  called  a  procedure  file.  You  opened  one  procedure  file  at  a  time, 
containing  up  to  32  procedures,  with  the  SET  PROCEDURE  command. 

dBASE  IV  handles  procedures  differently.  You  can  incorporate  them  directly 
into  a  program  file,  or  put  them  into  a  separate  procedure  file.  The  program 
or  procedure  file  can  contain  as  many  procedures  as  available  RAM  permits, 
up  to  a  maximum  of  1,170  procedures  per  file.  Each  procedure  must  begin 
with  the  keyword  PROCEDURE  and  end  with  RETURN. 

dBASE  IV  maintains  a  procedure  list  at  the  beginning  of  every  object  (.dbo) 
file.  It  treats  the  main  program  itself  as  a  procedure,  giving  it  a  procedure 
name  that  matches  the  source  program  filename.  This  procedure  name  is  the 
first  one  in  the  procedure  list.  Each  subsequent  procedure,  whether 
contained  in  the  current  source  file  or  in  a  separate  procedure  file,  is  added 
to  the  list  when  the  source  file  is  compiled  to  an  object  file. 

For  example,  suppose  you  have  the  following  hypothetical  program,  Main: 

*ftein.prg 

<camErds> 

DO  A 
DO  B 
DO  C 


PROCEDURE  A 
<camands> 
RETLRJ 


PROCaXRE  B 
<ccnrrBrds> 
RETUN 


PRDCEDLFE  C 
<ajiiiH'ds> 
RETIFN 
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dDASE  IV  will  include  four  procedures  in  the  procedure  list  for  the  com¬ 
piled  object  file:  Main  (the  default  procedure  name),  A,  B,  and  C.  Note  that 
only  the  code  at  the  beginning  of  a  program  file  is  assigned  the  default  pro¬ 
cedure  name.  Any  loose  code  following  RETURN  and  before  PROCEDURE 
will  be  compiled,  but  will  cause  a  warning  error  during  compilation.  As  this 
code  will  not  be  executed  by  the  DO  command,  the  compiler  verifies  that 
you  want  this  code  imbedded  in  your  program  and  object  code  files. 

Putting  the  procedures  in  the  main  program  file  eliminates  the  need  for 
many  separate  procedure  files.  This  makes  programs  run  more  quickly,  since 
dBASE  IV  does  not  have  to  open  and  close  these  programs  before  running 
them.  You  can  still  use (fHe)SET  PROCEDURE  TO  <  procedure  filename  > 
for  procedures  not  activateJwith  the  DO  command. 

When  dBASE  IV  encounters  a  DO  <  procedure  filename  >  command  in 
program  code,  it  searches  for  the  named  procedure  in  the  following  order: 

1.  Search  the  currently  executing  object  (.dbo)  file. 

2.  Search  the  SET  PROCEDURE  file,  if  one  is  active. 

3.  Search  other  open  object  files  (most  recently  opened  first). 

4.  Find  and  open  an  object  (.dbo)  file  of  that  name. 

5.  Find  and  compile  a  program  (.prg)  file  of  that  name. 

6.  Find  and  compile  an  SQL  program  (.prs)  file  of  that  name. 

Because  dBASE  IV  uses  this  search  order,  you  can  hide  procedures  of  the 
same  name  from  each  other.  You  can  also  still  use  the  SET  PROCEDURE 
command  to  open  a  procedure  file  for  the  DO  command  search. 

The  dBASE  IV  procedure  limits  are: 

■  64K  of  compiled  code  per  procedure 

■  32K  of  compiled  code  per  branch  (such  as  within  a  DO 
WHILE. .  .ENDDO  loop) 

■  32  active  object  (.dbo)  files  (includes  the  SET  PROCEDURE  TO  file) 

■  1,170  procedures  per  object  file  (practically  limited  by  RAM,  since  each 
entry  in  the  procedure  list  requires  about  25  bytes) 

The  Control  Center  generates  dBASE  IV  source  code  and  compiles  it  into 
object  code.  Some  dBASE  IV  commands  also  compile  object  code  from 
source  code  generated  by  a  design  screen.  For  example,  REPORT  FORM  will 
compile  an  .frg  file,  which  was  created  by  CREATE  REPORT,  into  an  .fro  file 
containing  object  code.  Since  dBASE  IV  handles  procedures  in  object  file 
form,  it  does  not  distinguish  between  procedures  created  by  DO,  COMPILE, 
and  DBLINK,  nor  between  object  code  in  format  (.fmo),  report  (.fro),  label 
(.lbo),  or  query  (.qbo)  files.  It  also  does  not  distinguish  between  object  code 
generated  from  .prg  files  and  SQL  program  (.prs)  files.  Any  object  code  pro¬ 
cedure  may  be  called  and  added  to  the  procedure  list. 
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Using  Commands 

This  section  discusses  required  and  optional  parts  of  a  command  line,  and 
includes  rules  for  building  expressions. 

The  structure  of  a  command  line  is  called  its  syntax.  Each  command  line 
begins  with  a  verb,  and  many  commands  also  have  one  or  more  clauses  that 
tailor  the  command  to  meet  a  need.  The  general  syntax  of  a  command  is 
described  below. 


NOTE 

You  will  find  many  exceptions  to  the  general  syntax  paradigm  given 
below.  Not  all  commands  use  all  the  options  given  in  this  paradigm. 
The  exceptions  are  covered  in  the  alphabetical  listings.  Read  each 
entry  in  the  subsequent  chapters  carefully,  before  using  any  language 
component. 


<  command  verb >  [<  expression  list >  ]  [<  scope >  ] 

[FOI .  <  condition  >  ]  [WHILE  <  condition  >  ]  [TO  FILE  <  filename  > 
/TO  PRINTER/  TO  ARRAY  <  array  list  >  /TO  <  memvar>  ] 

[ALL]  [LIKE/ EXCEPT  <  skeleton  >  ]]  [IN  <  alias  >  ] 

<  command  verb  >  is  the  name  of  the  dBASE  command. 


[  ]  (square  brackets)  indicate  that  the  item  is  optional. 

<  >  (angle  brackets)  indicate  that  you  must  supply  a  specific  value  of  the 
type  required  for  the  item  in  the  brackets. 

/  (slash)  indicates  an  either/or  choice. 


NOTE 

Do  not  type  the  square  brackets,  angle  brackets,  or  slash  when  enter¬ 
ing  a  command. 


<  list  >  m  eans  a  group  of  lil  e  item  s  separated  by  com m  as. 

[<  expression  list >  ]  is  one  or  more  expressions,  separated  by  commas. 
They  do  not  have  to  be  the  same  data  type  (see  the  “Expressions”  section 
below). 

[ <  scope  >  ]  indicates  the  number  of  records  the  com mand  can  access.  The 
keywords  for  scope  are: 

■  RECORD  <  n>  to  specify  a  single  record  by  its  number 

■  NEXT  <  n  >  for  n  records  beginning  with  the  current  record 

■  ALL  for  all  the  records  in  the  database 

■  REST  for  records  from  the  current  one  to  the  end  of  the  file/^ 

If  you  do  not  specify  a  scope,  ALL  is  assumed. 
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<  condition  >  is  a  comparison  between  two  or  more  items  like  Name  - 
’Smith'  or  a  logical  statement  like  .NOT.  EOF(). 

[FOR  <  condition  >  ]  tells  dBASE  IV  that  the  command  applies  only  to 
records  that  meet  the  condition. 

[WHILE  <  condition  >  ]  tells  dBASE  IV  to  repeat  the  command  as  long  as 
the  condition  is  true. 

[TO  ...]  controls  the  output  of  the  command.  You  can  send  the  output  to  an 
ASCII  text  file,  a  printer,  a  designated  array,  or  a  memory  variable. 

Memvars  (or  Memory  variables ,  or  just  variables)  are  data  values  you  tempo¬ 
rarily  store  in  RAM.  You  assign  each  of  these  values  a  name  so  that  you  can 
later  retrieve  it  from  memory  by  name.  Use  these  values  to  perform  calcula¬ 
tions,  comparisons,  and  other  operations.  You  create  memory  variables  with 
any  of  the  following  commands:  ACCEPT,  AVERAGE,  CALCULATE,  COUNT, 
INPUT,  PARAMETERS,  PUBLIC,  SUM,  STORE,  and  WAIT. 

The  DECLARE  command  creates  a  special  set  of  memory  variables  called  an 
array.  An  array  is  a  one- or  two-dimensional  table  of  values  stored  in  mem¬ 
ory.  Each  entry  in  the  array  is  called  an  element ,  and  each  element  in  an 
array  may  be  treated  like  a  memory  variable,  and  may  be  used  in  an^xpres- 
sion. 

[ALL  [LIKE/EXCEPT  <  skeleton  >  ]]  directs  dBASE  IV  to  include  or  exclude 
the  files  or  memory  variables  that  match  the  skeleton.  The  skeleton  is  a  gen¬ 
eral  pattern  that  filenames  or  memory  variable  names  may  match.  You  may 
use  the  ?  and  *  symbols  as  wildcards  in  the  skeleton.  A?  represents  any  sin¬ 
gle  character,  while  *  represents  a  group  of  any  characters. 

[IN  ...]  directs  dBASE  IV  to  look  in  a  different  work  area  for  the  designated 
expressions.  dBASE  allows  several  database  files  to  be  open  simultaneously 
by  allotting  each  open  file  its  own  unique  work  area. 

Internally,  dBASE  IV  keeps  track  of  a  database  by  its  filename,  alias  name, 
and  work  area  number.  If  you  don't  assign  an  alias  name  with  the  USE  com¬ 
mand,  dBASE  IV  uses  the  filename  as  the  alias  name.  The  expression 

<  alias  >  is  the  name  of  a  specified  work  area. 

dBASE  IV  has  ten  work  areas.  One  database  file  may  be  open  in  each  work 
area,  so  you  may  have  a  total  of  ten  database  files  open  simultaneously.  (If  a 
catalog  is  open,  you  may  only  open  nine  database  files.  See  the  SEt7cATA- 
LOG  command  in  chapter  3.)  When  you  open  a  database  file,  that  file  is  put 
in  the  currently  selected  work  area.  Use  the  SELECT  command  to  activate  a 
different  work  area.  When  you  SELECT  another  work  area,  the  files  you 
opened  in  the  other  work  areas  remain  open. 

The  IN  clause  allows  you  to  manipulate  the  database  file  in  another  work 
area  without  SELECTing  it  as  the  current  work  area.  IN  is  usually  followed 
by  the  alias  name  of  the  file  in  another  work  area.  (The  USE  command,  how¬ 
ever,  requires  a  work  area  number  in  the  IN  clause,  because  no  alias  exists 
until  after  the  file  is  opened.) 

<  filename >  may  be  the  actual  name  of  a  file  as  it  is  written  on  disk,  or  an 
indirect  reference  to  the  filename.  Indirect  references  are  discussed  in  the 
“Macro  Substitution”  section,  later  in  this  chapter. 
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dBASE  IV  accepts  any  valid  DOS  filename  When  you  write  a  file  to  disk, 
dBASE  IV  assigns  an  extension  to  the  file  that  indicates  the  type  of  informa¬ 
tion  it  contains.  For  example,  the  CREATE  command  will  write  a  file  with  a 
.dbf  extension,  which  indicates  to  other  dBASE  commands  that  the  file  con¬ 
tains  data  records.  Appendix  D  provides  a  complete  listing  of  the  dBASE  IV 
file  extensions. 


NOTE 

Do  not  use  a  DOS  device  name  as  a  filename.  Check  your  DOS  man¬ 
ual  for  DOS  device  names. 


Expressions 

An  expression  is  formed  with  any  combination  of: 

Field  names 
Memory  Variables 
Constants 
Functions 
Operators 

So  far  in  this  chapter,  you  have  already  encountered  memory  variables  and 
functions. 

A  field  name  is  the  name  of  one  field,  or  item  of  information,  contained  in 
every  record  of  a  database  file.  Lastname  might  be  the  field  name  of  a  field 
that  contains  clients’  last  names.  Each  record  in  the  database  file  would  typi¬ 
cally  have  one  client’s  last  name  entered  in  the  Lastname  field. 

If  the  field  is  not  in  the  currently-selected  database  file,  you  must  precede 
the  field  name  with  the  alias  name.  Use  the  alias  symbol  (->  )  between  the 
field  name  and  alias  name.  Note  that  you  enter  the  alias  symbol  with  two 
keystrokes,  a  hyphen  (-)  and  a  greater-than  symbol  (>  ).  For  example, 

C  L  i  errt->LastraTB 

means  the  Lastname  field  in  the  database  file  whose  alias  is  Client. 


NOTE 

When  fields  and  memory  variables  have  the  same  name,  fields  take 
precedence  over  memory  variables.  You  can  change  this  by  preceding 
the  memory  variable  name  with  M->  ,  as  in  M->  memvar. 


A  constant  is  a  literal  value  /m  bedded  right  in  the  expression,  such  as  "S'  (a 
character  constant),  or  2  (a  numeric  constant). 


Operators  are  symbols  that  link  memory  variables,  fields,  constants,  and 
functions  so  that  the  dBASE  IV  processor  can  evaluate  the  entire  expression 
as  one  unit.  The  types  of  operators  are  discussed  later  in  this  chapter. 
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When  you  combine  fields,  memory  variables,  constants,  or  a  function's 
returned  value  in  one  expression,  they  must  be  the  same  data  type.  See  the 
discussion  of  data  types  in  the  next  section.  If  necessary,  use  functions  to 
convert  elements  of  differing  data  types  to  one  common  type.  For  example, 
you  must  use  functions  to  convert  numeric  variables  to  character  data  type 
before  joining  them  with  character  constants.  The  expressions  in  an  expres¬ 
sion  list,  however,  do  not  have  to  be  of  the  same  data  type.  For  information 
on  which  functions  convert  data  types,  see  the  classification  ‘‘Conversion 
Functions”  in  Appendix  H. 


Data  Types 


There  are  four  data  types:  character ,  numeric,  date,  and  logical.  There  are 
really  two  numeric  types,  but  no  conversion  is  needed  between  these  two 
types.  These  are  discussed  below. 


Character  Type 

Character  type  fields,  constants,  and  variables  contain  character  strings 
Character  constants  must  be  bounded  with  delimiters,  such  as  double  quotes 
(DU),  single  quotes  fv),  or  brackets  ([  ]).  You  may  also  store  a  decimal 
sequence  to  a  character  string  with  the  CHR()  function.  For  example: 


/V  c  AT  Of  /•  fjo/ 

x  r  ££ 


.  STORE  'AT  TO  Metier 


.  STORE  OR (65)  TO  Mletter 


both  create  a  character  type  memory  variable  containing  the  letter  A 


Numeric  Types 


dBASE  IV  supports  two  numeric  data  types:  type  N and  type  F.  Type  N  num¬ 
bers  are  Binary  Coded  Decimal  (BCD)  numbers.  Type  F  numbers  are  the 
floating  point  binary  numbers  that  were  used  in  dBASE  III  PLUS.  The  dis¬ 
tinction  between  these  two  types  is  internal  to  dBASE  IV;  both  forms  look 
the  same  when  you  display  them. 

As  type  N  numbers  contain  a  decimal  representation  of  the  number,  they  are 
not  subject  to  rounding  errors.  They  are  useful  in  business  and  financial 
applications  where  totals  must  balance.  Type  F  numbers  are  more  useful  in 
scientific  applications,  when^dealing  with  very  large  or  very  small  numbers, 
-ofrAwhen  performing  repeated  multiplication  or  division.  Type  F  numbers, 
however,  may  yield  an  inaccurate  result  when  rounding  or  truncating. 
Therefore,  they  are  not  as  useful  as  type  N  numbers  in  business  and  financial 
applications. 

Numbers  that  you  input  into  dBASE  IV  are  type  N  by  default.  You  may  use 
the  FLOAT()  function  to  convert  these  numbers  to  type  F.  If  you  define  a 
database  field  as  type  F,  however,  you  may  enter  type  F  numbers  directly 
into  this  field  without  using  the  FLOXT()  function  for  conversion. 


y  *  u  *  r  e. 

'  A 

0*-  . 

*  e  y  /  £ 

*/  A. 
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Numeric  fields  imported  from  dBASE  III  PLUS  are  treated  as 
bers. 


type  N^num- 


If  a  function  or  command  returns  a  number,  its  number  type  depends  on  the 
function  or  command  and  the  input.  The  functions  EXP(),  LOG(),  SQRT(), 
and  all  the  trigonometric  functions  always  return  a  type  F  number.  All  other 
functions  return  either  a  type  N  number  or  the  same  type  as  the  input.  Note 
that  operations  that  combine  different  number  types  output  type  F  numbers. 

If  you  have  very  large  or^small  numbers,  both  type  F  and  type  N  numbers 
display  in  scientific  notation.  The  exponent  is  preceded  by  the  letter  E,  such 
as  E+3>9. 


Date  Type 

Use  date  type  fields  and  memory  variables  to  store  calendar  dates.  The  size 
of  a  date  variable  or  field  is  always  eight  bytes,  and  the  total  memory  require¬ 
ment  is  nine  bytes.  dBASE  IV  validates  date  variables  whenever  they  are 
entered  or  changed.  The  default  date  format  is  the  American  style, 
mm/dd/yy.  You  can  change  the  format  with  SET  DATE,  or  with  the  DATE 
setting  in  Config.db.  See  Chapter  6,  “Customizing  dBASE  IV,”  to  change 
Config.db  parameters. 


Logical  Type 

Logical  fields  and  variables  are  stored  as  true  (.T.)  or  false  (.F.).  Logical 
fields  or  variables  will  accept  T,  t,  Y,  or  y  for  true  and  F,  f,  N,  or  n  for  false. 
When  you  create  them  from  the  keyboard,  you  must  delimit  logical  values  by 
periods  (for  example,  STORE  .T.  TO  Mlogic). 


The  abbreviations  for  dBASE  IV  data  types  are: 

■  <  expC>  for  character  type 

■  <  expN >  for  Binary  Coded  Decimal  (BCD)  numeric  type 

■  <  expF>  for  floating  point  binary  numeric  type 

■  <  expL>  for  logical  type 
<  expD>  for  date  type 

{{NOTE  TO  REVIEWERS:  Is  <  expL>  ever  used?  I  think  we  always  call  it 
<  condition  >  ,  but  please  note  if  there  are  any  places  we  use  the  term 
\<  expL>  instead.  :Mike}} 
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Operators 

dBASE  IV  provides  four  types  of  operators:  mathematical ,  relational ,  logical , 
and  string. 

Mathematical  Operators 

Mathematical  operators  generate  numeric  results. 

+  Addition/Unary  Positive 

—  Subtraction/Unary  Negative 

*  Multiplication 

/  Division 

••  or  A  Exponentiation 
()  Parentheses  for  Grouping 


Relational  Operators 

Relational  operators  generate  logical  results,  that  is  rfrue  (.T.)  or  /alse  (  F.). 
You  can  use  relational  operators  with  character,  numeric,  or  date  expres¬ 
sions.  Both  expressions  you  use  in  a  relational  operation  must  be  of  the  same 
type. 


<  >  or  # 

<  * 

>  » 

S 


Less  than 

Greater  than 

Equal  to 

Not  equal  to 

Less  than  or  equal  to 

Greater  than  or  equal  to 

Substring  comparison  (For  example,  if  A  and  B  are  char¬ 
acter  strings,  A$B  returns  a  logical  true  if  A  is  either/iden- 
tical  to  B  or  contained  within  B) 


Logical  Operators 

Logical  operators  obtain  a  logical  result  from  comparing  two  expressions. 

.AND.  Logical  and 

.OR.  Logical  or 

.NOT.  Logical  not 

()  Parentheses  for  grouping 

String  Operators 

String  operators  concatenate  two  or  more  character  strings  into  a  single 
character  string. 

+  Trailing  spaces  between  the  strings  are  left  intact  when  the  strings 
are  joined^*" 

—  Trailing  spaces  between  the  strings  are  moved  to  the  end  of  the  last 
string^" 

()  Parentheses  for  grouping 
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Precedence  of  Operators 


Each  type  of  operator  has  a  set  of  rules  that  governs  the  order  in  which 
operations  are  performed.  These  are  called  the  order  of  precedence  for  the 
operator. 

Relational  and  string  operators  have  only  one  level  of  precedence,  and  are 
performed  in  order  from  left  to  right. 

Mathematical  Operators 

The  precedence  levels  for  mathematical  operators  are: 

1.  Unary  +  and  —  signs 

2.  Exponentiation 

3.  Multiplication  and  division 

4.  Addition  and  subtraction 


The  precedence  levels  for  logical  operators  are: 

1.  .NOT. 

2.  .AND. 

3.  .OR. 

Combinations  of  Operators 

When  several  of  the  four  types  of  operators  are  used  in  the  same  expression, 
the  precedence  levels  are: 

1.  Mathematical  or  string 

2.  Relational 

3.  Logical 

All  operations  at  the  same  precedence  level  are  performed  in  order  from  left 
to  right.  Use  parentheses  to  override  the  order  in  which  operations  are  per¬ 
formed.  Operations  within  the  inner  nested  parentheses  are  performed  first. 


Using  SET  Commands 


SET  commands  control  dBASE  IV’s  system  parameters  from  the  dot  prompt 
or  from  within  program  and  procedure  Hies.  Chapter  3  lists  and  annotates  all 
the  dBASE  IV  SET  commands.  Some  of  these  commands  have  default  set¬ 
tings  installed  when  you  start  dBASE  IV.  These  defaults  are  listed  in^Chapter 
6,  “Customizing  dBASE  IVX Tahl»  6-VAYou  can  also  learn  how  to  change 
these  default  settings  in  Clrapter  6. 
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You  can  initialize  any  of  the  SET  commands  from  the  dot  prompt.  These  are 
only  in  use  temporarily,  however,  as  all  SET  parameters  revert  to  their 
defaults  when  you  QUIT  *H3A3C  IV. — • 

There  are  two  common  syntaxes  for  SET  commands: 

SET  <  parameter >  ON/ OFF 
or 

SET  <  parameter  >  TO  <  expression  > 


Using  Functions 

Functions  perform  specialized  operations  that  augment  and  enhance  the 
dBASE  IV  commands.  Functions  evaluate  or  convert  data,  and  then  return  a 
result. 

dBASE  IV  functions  all  have  parentheses  after  the  function  name^(except  for 
the  (Sc^macro^function,  which  is  described  in  the  next  section!.  The  parenthe¬ 
ses  may  or  may  not  contain  parameters  to  be  evaluated.  ' 

Chapter  4  lists  and  annotates  the  dBASE  IV  functions. 


User-Defined  Functions 

dBASE  IV  allows  you  to  define  your  own  functions.  With  a  user-defined  func¬ 
tion  (UDF),  you  can  further  customize  your  database  operations  to  fit  your 
needs. 

A  UDF  is  a  procedure  file.  It  begins  with  the  FUNCTION  command,  and  con¬ 
tains  commands  and  a  parameter  list  that  it  uses  to  return  a  value.  The  UDF 
filename  cannot  be  an  existing  dBASE  IV  function  or  command. 

The  syntax  for  a  user-defined  function  is: 

<  UDF  filename  >  ([<  parameter  list  >  ]) 

The  <  UDF  filename  >  you  select  is  the  user-defined  function  procedure 
file.  The  optional  <  parameter  list >  passes  parameters  to  the  UDF  proce¬ 
dure  file.  Use  the  RETURN  command  in  the  procedure  file  to  return  the 
value  generated  by  your  UDF.  If  the  procedure  determines  that  there  is  no 
expression  to  return,  the  UDF  returns  a  logical  false  (  F:). 

Commands  Not  Allowed  in  User-Defined  Functions 

You  can  reference  most  commands  in  UDFs  without  restrictions;  others, 
however,  cannot  be  used  at  all. 

TVvo  commands  you  can  use  with  restrictions  are  CLEAR  and  READ:  CLEAR 
if  it  has  no  arguments,  READ  if  there  is  no  active  format  file. 
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The  following  commands  and  SET  commands  are  not  allowed  in  UDFs.  If 
you  use  any  of  them,  an  error  message  appears. 

APPEND 

AVERAGE 

BROWSE 

CHANGE 

COPY 

CREATE 

DELETE 

DIR 

DIRECTORY 

DISPLAY 

EDIT 

EXPORT 

HELP 

IMPORT 

INDEX 

INPUT 

INSERT 

JOIN 

LABEL 

LIST 

LOAD 

LOGOUT 

MODIFY 

PACK 

PROCEDURE 

REINDEX 

REPORT 

SAVE 

SET  CATALOG  TO 

SET  FIELDS  TO 

SET  FILTER  TO 

SET  ORDER  TO 

SET  RELATION  TO 

SET  VIEW  TO 

SORT 

SUM 

TOTAL 

UPDATE 

ZAP 

Macro  Substitution 

The  macro  substitution  (&)  function  instructs  dBASE  IV  to  retrieve  the  con¬ 
tents  of  a  variable,  and  not  the  variable  name  itself.  To  use  it,  simply  place 
the  &  symbol  before  the  variable  name: 

.  S7CRE  ' Lastnatm ,  Firstrmef  TO  Mfields 
.  LIST  SMfields 


In  this  example,  LIST  AMfields  is  equivalent  to  LIST  Lastname,  Firstname. 
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The  macro  substitution  function  allows  you  to  prompt  the  user  for  a  piece  of 
information  in  a  program,  and  immediately  use  that  information  as  part  of  a 
command.  With  macro  substitution,  you  can  build  part  of  a  command  and 
allow  the  user  to  supply  certain  arguments. 

When  you  use  a  macro,  dBASE  IV  assumes  that  the  command  line  cannot  be 
compiled  at  compile  time.  When  the  command  is  encountered  at  runtime,  it 
is  expanded  using  the  current  value  of  the  memory  variable  following  the  &, 
and  the  full  compiler  is  called  in  once  again  to  compile  the  command.  This 
slows  down  processing  time. 

There  are  two  ways  you  can  speed  up  processing  time: 

1.  Use  an  indirect  reference  to  a  filename  rather  than  macro  substitution. 

An  indirect  reference  is  a  character  expression  that  evaluates  to  a  filename. 
You  must  use  an  operator  in  the  expression  so  that  dBASE  IV  knows  the 
character  string  is  an  expression,  not  the  literal  filename.  For  example,  anjf 
indirect  reference  may  be  used  in  the  CREATE  command  in  place  of  a  file¬ 
name.  If  the  variable  Mfile  contains  the  character  string  'Assembly', 

CREATE  (Mfile)  and  CREATE  RTRIM(Mfile)  will  create  a  database  file  named 
Assembly.  These  commands  are  the  same  as  CREATE  Assembly.  CREATE 
Mfil<4  +  <^)I®  will  create  a  database  file  named  AssemblyOl. 

An  indirect  reference  is  similar  to  using  the  macro  substitution  character,  as 
CREATE  &Mfile,  but  operates  much  faster. 

In  tl^e  following  example,  the  first  USE  command  will  call  in  the  compiler  at 
runtime,  while  the  second  USE  command  will  not: 


Mfiler  Client 
USE  ffljfile 
USE  MyileQ 


2.  When  possible,  use  macros  only  in  expressions,  and  SET  EMACRO  ON. 


dBAS  E  IV  allows  you  to  use  a  macro  with  a  variable  in  place  of  a  command, 
such  as: 


□ 


.  Ccrnerd  =  [RESET  IN  1] 


If  you  do  this,  of  course,  dBASE  IV  must  compile  the  command  at  runtime. 

If  you  use  macro  expansion  only  in  expressions,  most  of  the  command  can 
be  compiled  at  compile  time,  and  there  is  no  need  to  call  in  the  compiler 
again'  at  runtime.  You  must  notify  dBASE  IV  that  you  are  using  macros  only 
in  expressions,  not  in  place  of  command  verbs,  by  SETting  EMACRO  ON. 
(EMACRO  stands  for  “expression  macro.”) 


For  more  examples  of  how  macro  substitution  works,  see  the  discussion  of 
the  &  function  in  Chapter  4,  “Functions.”  Don’t  confuse  macro  substitution 
with  macros,  in  which  you  store  a  series  of  keystrokes. 
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Using  System  Memory  Variables 

System  memory  variables  are  memory  variables  that  dBASE  IV  automatically 
maintains.  They  control  the  appearance  of  printed  and  screen  output  and 
also  store  printer  settings.  More  specifically,  they  control: 

■  Characteristics  of  print  jobs,  such  as  form  feeds,  pauses  for  cut  sheet 
printing,  and  the  number  of  copies  printed 

■  The  appearance  of  paragraphs,  such  as  alignment,  indentation,  and /  mar- 
gins 

■  The  appearance  of  the  printed  page,  such  as  the  print  pitch,  print  quality, 
page  length,  and  page  left  offset 

The  names  of  all  system  variables  start  with  an  underscore  (_)  character,  to 
distinguish  them  from  ordinary  memory  variables.  (You  may  not  define  any 
other  memory  variables  starting  with  an  underscore.)  A  system  variable  that 
you  use  exclusively  for  controlling  your  printer  has  a  p  in  front  of  the  char¬ 
acteristic  it  controls. 

Upon  start-up,  dBASE  IV  automatically  initializes  system  variables  to  their 
defaults.  You  can  set  their  values  through  the  report  form  and  label  form 
design  screens,  at  the  dot  prompt,  or  in  a  program. 

You  can  see  the  relationships  among  the  page  formatting  system  variables  in 
Figure  1-1.  These  variables  are: 

■  .plength;  page  length 

■  _pwidth;  page  width 

■  _ploffset;  page  offset  from  left  edge 

■  .lmargin;  left  margin  from  _ploffset 

■  _rmargin;  right  margin  column  number 

■  .indent;  paragraph  indent 
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pfength 


-pvldth 


ON  PACE 
a<  lln* 


-rmarqin 


Figure  1  -1  Page  layout  for  typical  printjob 

You  will  find  complete  discussions  of  the  above  variables  in  Chapter  5, 
“System  Memory  Variables." 


Print  Form  File 

The  report  form  and  label  form  design  screens  handle  system  variables  for 
you.  When  you  create  a  report  (CREATE/ MODIFY  REPORT)  or  label7(CRE- 
ATE/MODIFY  LABEL),  you  can  store  the  changed  system  variable  definitions 
to  a  binary  print  form  file.  This  file  normally  has  the  same  name  as  the  report 
or  label,  with  the  file  extension  .prf. 

dBASE  IV  activates  this  print  form  file  when  you  next  modify  the  report  or 
label,  or  when  you  select  Use  print  form  from  the  Print  Menu.  The 
REPORT  FORM  command,  however,  does  not  automatically  activate  the 
print  form.  You  must  determine  print  settings  prior  to  issuing  REPORT 
FORM  by  setting  _pform  equal  to  the  print  form  filename,  or  by  making 
changes  to  individual  system  variables. 

When  you  have  finished  running  a  program  containing  system  variable  set¬ 
tings,  the  variables  automatically  revert  to  their  original  settings.  You  cannot 
RELEASE  these  variables. 

Other  parameters  affecting  the  printed  page  are  contained  in  ON  PAGE  AT 
LINE  and  the  footer/header  procedure  files.  See  the  ON  PAGE  description 
and  footer/header  examples  in  Chapter  2,  “Commands.” 
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?/??  displays  the  value  of  one  or  more  expressions.  ?/??  roughly  translates  to: 
‘‘What  is  .  .  .  ?”  or  “What  is  the  value  of  .  .  .  ?”  or,  simply,  “Print  .  . 

Syntax 

?/??[<  expression  1  >  [PICTURE  '  <  clause  >  *] 

[FUNCTION  "  <  function  list  >  "]  [AT  <  expN  >  ] 

[STYLE  <  font  number >  ]] 

[,<  expression  2  >  ...] 


Usage 

If  SET  PRINT  is  ON,  the  output  of  the  ?  command  is  sent  to  the  printer. 

The  single  question  mark  command  issues  a  carriage  return  and  line  feed 
before  displaying  the  results  of  the  expression  list.  The  double  question  mark 
does  not. 

??  displays  the  expression  list  starting  at  the  current  cursor  or  printer 
position. 

You  can  enter  as  many  expressions  and  clauses  as  will  fit  in  the  1024- 
character  command  line. 


Options 

The  PICTURE  or  FUNCTION,  AT,  and  STYLE  options  let  you  customize  the 
appearance  of  printed  reports. 

PICTURE  templates  and  functions  format  the  output.  All  the  templates  work 
with  the  ?/??  command.  See  the  @  command  for  a  description  of  templates. 


Six  functions  that  work  with  the  ?/??  command  handle  long  fields,  w h ic h  are 
fields  whose  contents  exceed  the  PICTURE  template,  and  short  Helds,  which 
are  fields  whose  contents  do  not  completely  fill  up  the  PICTURE  template. 
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?/?? 


Two  of  these  functions,  H  and  V,  are  available  only  for  use  with  the  ?/?? 
command.  Precede  these  functions  with  the  FUNCTION  or  PICTURE  key¬ 
word,  as  shown  under  “Special  Case,”  below. 

H<  n>  lets  the  field  stretch  horizontally  to  accommodate  data. 

V<  n>  lets  the  field  stretch  vertically  to  accommodate  data. 

<  n  >  is  the  maximum  number  of  columns  or  rows  in  the  field  display. 

Using  the  H  or  V  function,  you  can  modify  the  height  or  width  of  the  display. 
The  H  function  stretches  long  fields  horizontally  to  the  right,  pushing  ahead 
any  text  on  the  same  line.  It  shrinks  short  fields  to  the  left,  also  pulling  other 
text  on  the  same  line  to  the  left.  It  will  not  pull  other  text  on  the  line,  how¬ 
ever,  if  a  column  is  specified  with  the  AT  option.  The  V  function  stretches 
long  fields  vertically  down  the  page,  in  columnar  fashion. 

You  can  limit  how  far  a  field  stretches  by  indicating  the  maximum  number 
of  columns  or  rows  allowed  for  the  field.  Any  additional  characters  will  be 
truncated.  Without  the  <  n>  ,  the  field  will  grow  to  accommodate  its  entire 
contents. 

If  you  don’t  specify  the  H  and  V  functions,  the  field  width  is  fixed  by  the  tem¬ 
plate,  and  extra  characters  are  truncated.  The  field  height  defaults  to  one 
line. 

The  other  four  functions  align  short  fields,  and  can  also  be  used  with  the  @ 
command. 

5  Left-aligns  text  within  a  field. 

I  Centers  text  within  a  field. 

J  Right-aligns  text  within  a  field. 

T  Trims  leading  and  trailing  blanks  from  a  field. 

Short  fields  contain  text  tha  does  not  completely  fill  the  defined  PICTURE 
template.  If  you  want  to  trim  a  field  before  aligning  it,  list  the  T  function 
along  with  one  of  the  other  three  functions.  If  you  specify  no  alignment, 
strings  are  left-aligned  and  numbers  right-aligned. 

The  ?/??  command  also  supports  two  other  functions,  S  and  L.  The  $  func¬ 
tion  displays  a  floating  currency  symbol  before  or  after  the  amount.  If  SET 
CURRENCY  is  LEFT,  the  symbol  displays  just  before  the  amount.  If  SET 
CURRENCY  is  RIGHT,  it  displays  just  after  the  amount.  The  L  function  dis¬ 
plays  a  short  field  with  leading  zeros. 

AT  specifies  the  column  at  which  the  expression  displays.  Use  this  option  to 
print  columns  of  text  which  must  line  up,  regardless  of  the  length  of  printed 
text  to  the  left  of  the  column. 

STYLE  prints  the  text  in  various  styles,  such  as  bold  or  italic.  Depending 
upon  your  monitor,  STYLE  may  not  change  the  output  displayed  on  the 
screen,  but  will  affect  the  printed  output.  The  STYLE  clause  can  consist  of 
letters,  numbers,  or  a  combination  of  the  two. 
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The  allowed  letters  are: 

B  -  bold 
I  •  italic 
U  -  underline 
R  -  raised  (superscript) 

L  -  lowered  (subscript) 

The  allowed  numbers  are  1  through  5. 

The  numbers  correspond  to  fonts  that  you  have  previously  defined  in 
Config.db,  using  the  PRINTER  setting  (see  Chapter  6,  “Customizing 
dBASE  IV“). 

You  may  combine  different  styles,  and  print  different  text  on  the  same  line  in 
different  styles  (see  “Examples,”  below). 

You  can  also  use  the  ???  command,  and  the  system  memory  variables 
_pscode  and  .pecode,  to  change  typestyles.  In  general,  use  ?/??with  its 
STYLE  option  to  change  typestyles  of  individual  text  items,  ???  to  change 
typestyles  on  a  broader  basis  within  a  document,  and  _pscode  and  _pecode 
to  define  the  overall  typestyle  for  a  document.  (See  Chapter  5  for  informa¬ 
tion  on  the  system  memory  variables.) 


Tips 

?  without  an  expression  displays  a  blank  line,  and  can  be  used  to  skip  a  line 
in  the  output.  To  single- or  double-space  the  output,  however,  use  the 
_pspacing  system  memory  variable. 


Special  Case 

The  alignment  and  stretch  functions  discussed  above  interact  with  the  .wrap 
system  variable  in  the  case  of  printing  memo  fields.  (This  section  refers  to  a 
number  of  the  dBASE  IV  system  variables.  See  Chapter  5,  “System  Memory 
Variables,”  for  details.) 

If  you  stretch  the  field  horizontally  with  the  H  function,  dBASE  IV  ignores 
the  margins  embedded  in  the  memo  field,  and  instead  wraps  the  text 
between  the  .lmargin  and  .rmargin. 

If  you  stretch  the  field  vertically,  dBASE  IV  wraps  the  text  according  to  the 
display  width  of  the  template  that  you  specify. 

In  either  case,  dBASE  IV  honors  paragraph  breaks,  paragraph  indentation, 
and  alignment  contained  in  the  memo  field. 
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?/?? 


Use  the  B,  I,  or  J  function  to  override  an  overall  .alignment  setting,  or  indi¬ 
vidual  paragraph  alignments,  in  a  memo  field.  The  following  routine  centers 
a  memo  field,  named  Notes,  and  stretches  it  vertically  within  the 
15-character  display  column  defined  by  a  PICTURE  template.  The  field  cen¬ 
tering  overrides  the  initial  .alignment  =  "LEFT"  setting. 

.alignment  =  "LEFT 
.wrap  =  .T. 

?  Notes  PICTURE  "  1XXXXXXXXXXXXXX*  FLNCTICN  "VT 

If  you  had  stretched  the  field  horizontally  rather  than  vertically  in  the  previ¬ 
ous  example,  the  text  would  be  centered  between  .lmargin  and  .rmargin. 

If  .wrap  is  set  to  false  (.F.)  when  you  print  a  memo  field  using  the  H  func¬ 
tion,  the  memo  field  starts  printing  at  the  current  column  (PCOL()  or 
.pcolno),  and  that  column  becomes  the  effective  .ploffset.  dBASE  IV  hon¬ 
ors  any  page  breaks,  margins,  and  indentation  contained  in  the  paragraphs. 

Examples 

From  the  Qient  database  file,  to  print  the  Client.id  and  the  Client  field  val¬ 
ues  in  bold  and  the  value  of  Lastname  in  italics: 


.  USE  Client 
.  SET  PRINT  CN 

.  ?  CL  ientJd  STYLE  T,  CL  rent  STYLE  Lastretre  STYLE  T 

/ram  voeir  &  soc,  ltd  r  


Overstriking  text  is  sometimes  useful  to  show  changes  made  to  a  document. 
To  overstrike  a  line  of  text  f  om  a  program  file,  use  the  AT  option  with 
.wrap  set  to  false  (.F.).  (Chapter  5  discusses  .wrap  and  the  other  system 
memory  variables.) 

.wrap  -  „F. 

SET  FRINT  CN 

?  "Ps-riing  receipt  of  file." 

??  "////////////////////////File  received  3/7/88*  AT  0 

To  overwrite  rather  than  overstrike  text,  use  the  technique  just  shown  with 
.wrap  set  to  true. 

See  Also 

???,  @,  SET  PRINT 

Chapter  5,  “System  Memory  Variables” 

Chapter  6,  “Customizing  dBASE  IV^ 
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???  sends  output  directly  to  the  printer,  bypassing  the  installed  printer  driver. 

Syntax 

???  [<  expC>  ) 

Usage 

You  may  use  the  ???  command  to  send  characters  to  your  printer  that  will 
not  change  the  printer’s  current  row  and  column  position.  You  usually  send 
printer  control  codes  when  the  printer  driver  does  not  support  a  particular 
printing  capability. 

The  ?/??  command  and  the  system  memory  variables  _pscode  and  _pecode 
also  send  printer  control  codes  to  the  printer.  In  general,  use  ?/??  (STYLE 
option)  to  change  typestyles  of  individual  text  items,  ???  to  change  typestyles 
on  a  broader  basis  within  a  document,  and  _pscode  and  _pecode  to  define 
the  overall  typestyle  for  a  document. 

Printer  control  codes  are  specific  to  the  printer  you  are  using.  Consult  your 
printer  manual  for  the  necessary  control  codes. 

Printer  control  codes  may  include  any  printable  character  except  the  double 
quote  mark  (*),  as  well  as  non-printable  characters,  such  as  Esc.  You  can 
define  these  non-printable  characters  in  a  variety  of  ways. 

Control  character  specifiers  are  strings  that  identify  non-printable  characters. 
You  must  include  the  curly  braces  ({}). 
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Table  2-1  Control  character  specifiers 


ASCII  Code  Control  Character  Specifier 


0 

{NULL}  or  {CTRL-@ } 

1 

{CTRL-A} 

2 

{CTRL-B} 

3 

{CTRL-C} 

4 

{CTRL-D} 

5 

{CTRL-E} 

6 

{CTRL-F} 

7 

{BELL}  or  {CTRL-G} 

8 

{BACKSPACE}  or  {CTRL-H} 

9 

(TAB}  or  {CTRL-I} 

10 

{LINEFEED}  or  {CTRL-J} 

11 

{CTRL-K} 

12 

{CTRL-L} 

13 

{RETURN}  or  {CTRL-M} 

14 

{CTRL-N} 

15 

{CTRL-O} 

16 

{CTRL-P} 

17 

{CTRL-Q} 

18 

{CTRL-R} 

19 

{CTRL-S} 

20 

{CTRL-T} 

21 

{CTRL-U} 

22 

{CTRL-V} 

23 

{CTRL-W} 

24 

{CTRL-X} 

Ccorthi 
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Table  2-1  Control  character  specifiers  (continued) 


ASCII  Code 

Control  Character  Specifier 

25 

{CTRL-Y} 

26 

{CTRL-Z} 

27 

{ESC}  or  {ESCAPE}  or  {CTRL-{} 

28 

{CTRL-\} 

29 

{CTRL-]} 

30 

{CTRL-A} 

31 

{CTRL-.} 

127 

PEL}  or  PELETE} 

Examples 

Suppose  you  want  to  send  an  Esc-E  to  an  HP  LaserJet  printer.  (This  code 
resets  the  printer.)  Knowing  that  the  ASCII  code  for  Esc  is  27  and  an  E  is 
code  69,  you  can: 

Use  the  CHR()  function,  which  converts  a  number  to  its  ASCII  character 
equivalent: 

.  ???  CHHZ7)  +  ’F 

Use  control  character  specifiers: 

.  ???  ’{ESOF 

Use  entirely  ASCII  codes,  enclosing  the  codes  within  curly  braces: 

.  ???  ’GTHjSPy 

Use  a  combination  of  ASCII  codes  and  letters: 

.  ???  ’<27}C 
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@  displays  information  in  a  specified  format  at  a  given  set  of  coordinates, 
and  may  optionally  allow  you  to  edit  the  information. 


Syntax 

@  <  row  >  ,  <  col  > 

[  [SAY  <  expression  >  [PICTURE  *  <  clause  >  '] 

[FUNCTION  *  <  function  list>  ']] 

[GET  <  variable  >  [[OPEN]  WINDOW  <  window  name>  ] 

[PICTURE  '  <  clause  >  ']  [FUNCTION  "  <  function  list>  '] 
[RANGE  <  low  >  ,<  high>  ]  [VALID  <  condition  >  ]  [ERROR 
<  expC>  ]] 

[WHEN  <  condition  >  ]  [DEFAULT  <  expression  >  ] 
[MESSAGE  <  expC>  ] 

[COLOR  [<  standard  >  ]  [,<  enhanced  >  ]]  ] 


Usage 

<  row  >  and  <  col>  are  numeric  expressions.  For  a  25  x  80  terminal, 

<  row  >  can  range  from  0  to  24  and  <  col>  from  0  to  79.  If  you  SET 
DEVICE  TO  PRINTER,  the  <  row  >  can  be  from  0  to  32,767  and  <  col> 
can  be  from  0  to  255. 

With  SET  STATUS  ON,  line  22  on  the  screen  is  reserved  for  the  status  line.  If 
you  SET  STATUS  OFF  and  do  not  SET  SCOREBOARD  OFF,  line  0  is  used  for 
status  information  display.  To  free  these  lines  for  other  use,  you  must  SET 
STATUS  OFF  and  SET  SCOREBOARD  OFF. 

If  you  change  a  field  that  affects  the  results  of  other  calculations  (or  other 
fields’  defaults)  which  are  defined  in  the  form,  then  these  calculations  are 
performed  and  the  results  appear  on  the  screen. 

The  SAY  keyword  displays  information  that  you  do  not  want  to  change.  The 
value  of  any  valid  dBASE  IV  expression  can  be  displayed. 

The  GET  keyword  displays  and  allows  editing  of  data  values  contained  in 
fields,  or  currently  assigned  to  memory  variables  or  arrays.  The  READ  com¬ 
mand  activates  the  GETs  and  a  full-screen  editing  mode  which  lets  you 
change  the  GET  fields. 

Besides  using  GETs  with  the  READ  command,  you  can  create  a  format  (.fmt) 
file  that  contains  @  commands.  (Format  files  are  text  files  that  can  be  cre¬ 
ated  with  the  MODIFY  COMMAND  program  editor  or  another  text  editor.) 
CREATE/MODIFY  SCREEN  helps  you  lay  out  an  input  or  output  screen,  and 
generates  an  .fmt  file  that  contains  @  commands.  You  can  use  a  format  file 
with  the  APPEND,  CHANGE,  EDIT,  INSERT,  and  READ  commands. 
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You  can  use  SET  DEVICE  TO  PRINT  to  route  @  commands  to  the  printer. 
GETs  are  not  routed  to  the  printer.  Most  printers  have  limitations  on  the  row 
and  column  coordinates.  When  sending  @  commands  to  a  printer,  decreas¬ 
ing  the  row  number  in  consecutive  @  commands  causes  a  page  eject.  Simi¬ 
larly,  if  two  @  commands  have  the  same  row  coordinate,  the  second  one 
must  have  a  larger  column  coordinate. 


Options 

The  options  of  the  @  command  are  described  in  alphabetical  order. 

@  <  row  >  ,  <  col  >  —  Without  any  options,  the  @  comm  and  clears  the 
specified  row  beginning  at  the  specified  column  position. 

COLOR  —  Specifies  the  colors  used  for  the  SAY  and  GET  variables.  The 
<  standard >  color  is  used  for  SAYs,  the  <  enhanced  >  color  for  GETs,  and 
they  follow  the  same  rules  as  these  options  in  the  SET  COLOR  command. 

You  can  specify  a  foreground  and  background  color  for  each  one.  See  the 
SET  COLOR  command  for  information  on  using  these  codes  to  change  the 
colors  of  the  screen  display. 

Either  the  standard  or  enhanced  colors  can  be  left  unchanged  by  omitting  a 
color  code.  If  you  leave  out  the  standard  code,  but  want  to  change  the 
enhanced  colors,  you  should  precede  the  enhanced  code  with  a  comma  so 
that  the  command  parser  can  determine  that  the  standard  code  has  not  been 
changed.  For  example,  to  change  the  enhanced  color  to  white  characters  on 
a  red  background: 

.  9  2^20  GET  Text  COLOR  MR 

The  colors  you  specify  override  the  SET  COLOR  command,  but  only  for  the 
output  of  the  current  @  command. 

DEFAULT  —  Use  the  expression  to  put  a  preset  value  into  a  GET  variable;  it 
must  match  the  GET  variable’s  data  type.  The  expression  is  evaluated  only 
when  you  add  records  to  a  database  file.  The  DEFAULT  expression  appears  in 
the  GET  variable,  and  pressing  ♦♦  assigns  the  value  to  the  GET  variable. 

ERROR  —  <  expC>  is  any  valid  character  expression.  Use  this  option  to 
display  your  own  message  when  the  VALID  <  condition  >  is  not  met.  Your 
message  overrides  dBASE  IV’s  message,  Editing  condition  not  satisfied. 

FUNCTION  —  The  FUNCTION  option  is  similar  to  the  PICTURE  option.  See 
the  description  of  PICTURE  below . 
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MESSAGE  —  <  expC>  must  be  a  valid  character  expression,  which  then 
appears  when  a  READ  is  executed  and  the  cursor  is  placed  in  the  GET  field 
associated  with  the  message.  If  SET  STATUS  is  ON,  the  message  is  centered 
on  the  bottom  line  of  the  screen.  If  SET  STATUS  is  OFF,  the  message  appears 
in  the  upper  right  corner  of  the  screen.  The  message  will  not  appear  if  both 
SET  SCOREBOARD  and  SET  STATUS  are  OFF.  This  command  temporarily 
overrides  a  SET  MESSAGE  expression. 


WINDOW  —  When  the  cursor  is  moved  to  a  memo  field  and  Ctrl-Home  is 
pressed,  the  memo  field  can  be  edited.  If  the  WINDOW  option  is  not  speci¬ 
fied  along  with  GET,  the  default  window  from  SET  WINDOW  OF  MEMO  is 
used.  If  no  window  was  set,  then  the  full  screen  is  used  for  editing  the  memo 
field.  If  the  OPEN  WINDOW  phrase  is  specified,  the  window  is  activated  and 
the  memo  field  can  be  edited  inside  the  window.  When  you  exit  from  the 
memo  field  editor,  the  window  is  deactivated,  the  background  is  restored, 
and  the  cursor  returns  to  the  memo  field  marker. 
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OPEN  WINDOW  —  Use  this  option  to  specify  a  window  name  (as  with  the 
WINDOW  option),  but  also  to  specify  that  the  window  should  be  open  with¬ 
out  requiring  the  user  to  press  Ctrl-Home. 

PICTURE  —  Use  this  option  to  restrict  the  type  of  data  that  may  be  entered 
into  a  variable,  or  to  format  the  result  of  an  expression.  The  clause  may  con¬ 
sist  of  a  function,  which  is  preceded  by  an  @  symbol  and  effects  all  the  input 
or  output  characters,  and/or  a  template ,  which  effects  input  or  output  on  a 
character  by  character  basis.  The  clause  must  be  delimited. 


PICTURE  functions  and  templates  are  described  in  greater  depth  in  the  sec¬ 
tions  below  Functions  may  also  be  used  with  the  FUNCTION  option,  and 
these  do  not  need  to  be  preceded  with  the  @  symbol. 

RANGE  —  Use  this  option  with  character,  numeric  and  date  variables  to 
specify  lower  and  upper  bounds.  The  <  low  >  and  <  high  >  expressions 
must  be  the  same  data  type.  They  define  the  minimum  and  maximum 
values  that  may  be  entered  in  response  to  the  GET.  The  RANGE  values  are 
inclusive. 

Enter  only  one  expression  if  you  want  to  specify  only  a  lower  or  upper  limit. 
You  must  include  the  comma  (,)  as  in  RANGE  ,30  or  RANGE  10,  .  The 

comma  helps  the  command  parser  determine  whether  you  supplied  the 
<  low  >  or  <  high  >  value.  If  you  then  enter  an  invalid  number  or  date, 
dBASE  IV  prompts  for  a  new  value  until  a  valid  number  or  date  is  entered. 

If  the  RANGE  criteria  are  not  met,  the  following  messages  may  appear: 

■  RANGE  is<m>  to<n>  —  the  upper  and  lower  lim  its  are  out  of 
range. 

■  Lower  bound  is  <  n>  —  only  a  lower  limit  is  specified  and  incorrect. 


Upper  bound  is 

incorrect. 


:  m  >  —  only  an  upper  limit  is  specified  and 
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<  m  >  and  <  n  >  are  the  values  specified  in  the  RANGE  statement. 


If  you  specify  a  RANGE  and  press  ♦♦  in  response  to  a  GET,  no  range  check¬ 
ing  is  done.  Therefore,  if  a  field  or  variable  is  set  to  a  value  outside  the  speci¬ 
fied  range,  pressing  ♦♦  leaves  the  value  unchanged. 

VALID  —  This  option  can  state  a  condition  that  must  be  met  before  data  is 
accepted  into  the  GET  variable.  If  the  condition  is  not  met,  the  message 
Editing  condition  not  satisfied,  or  the  message  you  defined  with  the 
ERROR  option  appears. 


NOTE 

You  can  enter  a  user-defined  function  as  the  VALID  condition,  if  the 
function  returns  a  logical  value.  This  enables  you  to  have  quite  power¬ 
ful  and  extensive  data  validation.  Refer  to  Chapter  1,  “Essentials,”  for 
more  information  on  user-defined  functions. 


WHEN  —  You  can  provide  a  condition  that  is  evaluated  when  you  try  to 
move  the  cursor  into  a  GET  field.  If  the  condition  is  true  (  T.),  the  cursor 
moves  into  the  field  for  you  to  edit.  If  the  condition  is  false  (  F.),  the  cursor 
skips  the  field  and  moves  to  the  next  one. 


Format  Functions 


You  may  use  format  functions  with  the  PICTURE  or  FUNCTION  options,  or 
with  the  TRANSFORM  function. 

If  you  use  a  format  function  in  a  PICTURE  clause,  the  @  symbol  must 
appear  as  the  first  character  in  the  clause.  If  you  use  a  format  function  with 
the  FUNCTION  option,  the  @  symbol  is  not  needed.  If  you  use  both  a  format 
function  and  a  template  in  a  PICTURE  clause,  a  space  must  separate  the  two. 
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dBASE  IV  provides  the  following  format  functions: 

Table  2-2  Format  functions  used  in  dBASE  IV/ 


Function 

! 

A 

$ 

( 

A 

B 

C 

D 

E 

I 

J 

L 

M 

R 

S<  n  > 

T 

X 

Z 


Description 

Allows  any  character  and  converts  letters  to  upper  case. 
Displays  numbers  in  scientific  notation. 

Displays  data  in  currency  format. 

Encloses  negative  numbers  in  parentheses. 

Alphabetic  characters  only. 

Left-aligns  text  within  a  Held. 

Displays  CR  (credit)  after  a  positive  number. 

American  date  format. 

European  date  format. 

Centers  text  within  a  field. 

Right-aligns  text  within  a  field. 

Displays  leading  zeros. 

Allows  a  list  of  choices  for  a  GET  variable. 

Displays  literal  characters  in  the  template,  but  doesn’t  enter 
them  in  the  field. 

Limits  field  width  display  to  <  n  >  characters  and  horizontally 
scrolls  the  characters  within  it  in  <n>  columns.  <n>  must 
be  a  literal  positive  integer. 

Trims  leading  and  trailing  blanks  from  a  Held. 

Displays  DB  (debit)  after  a  negative  number. 

Displays  zero  numeric  value  as  a  blank  string. 


Some  functions  are  restricted  according  to  the  data  types  to  which  they 
apply: 

■  The  functions  $,  (,  B,  C,  L,  X,  and  Zcan  be  used  only  with  numeric  data 
(either  type  N  or  type  F).  Furthermore,  $,  (,  C,  L,  and  X  can  be  used  only 
to  display  data  (that  is,  with  the  SAY  clause). 

■  D  and  E  apply  only  to  date  data. 
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■  <  ,  A,  M,  R,  and  S>  n!  are  relevant  only  to  character  data. 


You  can  define  new  format  functions  by  combining  the  functions  in  the 
table.  For  example,  the  function  XC  displays  DB  after  negative  numbers  and 
CR  after  positive  numbers.  However,  you  cannot  use  some  functions 
together,  such  as  D  and  E. 

You  can  use  the  A  exponent  function  with  SAY,  GET  and  TRANSFORM().  It 
works  with  both  type  N  and  type  F  numbers.  The  specified  expression  is  dis¬ 
played  in  the  following  format,  with  the  letter  S  indicating  a  sign: 

s7|w  nttt 

If  the  number  does  not  include  a  sign,  the  sign  position  is  a  blank.  If  the 
number  is  negative,  dBASE  IV  automatically  includes  a  negative  sign. 


The  number  of  spaces  before  E  depends  on  the  field  width  you  defined  in  the 
database  structure.  For  memory  variables,  the  number  of  spaces  is  equal  to 
10,  minus  the  number  of  significant  digits  in  the  variable.  If  the  field  (type  N 
or  F)  has  no  decimal  places,  the  number  of  spaces  is  the  field  width  plus  1.  If 
the  field  has  one  or  more  decimal  places,  the  number  of  spaces  equals  the 
field  width.  For  example,  in  a  field  six  digits  wide,  5,678,000  would  appear 
as: 

5^78  E6. 

There  are  six  spaces  between  the  number  and  the  exponent.  When  convert¬ 
ing  numbers  with  or  without  a  sign,  the  A  function  automatically  aligns  deci¬ 
mal  places. 

The  S  function  displays  the  expression  with  the  currency  symbol  immediately 
before  the  amount.  You  can  only  use  this  function  in  GETs  if  SET 
CURRENCY  is  LEFT.  The  currency  symbol  you  want  to  use,  this  symbol’s 
placement  in  the  display,  the  separator  characters,  and  the  decimal  symbol 
can  be  changed  with  the  SET  CURRENCY,  SET  SEPARATOR,  and  SET 
POINT  commands. 

Use  S<  n  >  to  display  and  edit  a  character  GET  variable.  The  number  of 
columns  you  specify,  by  the  literal  integer  <  n  >  ,  must  be  less  than  the 
actual  length  of  the  character  field  or  memory  variable.  Do  not  put  any 
spaces  between  the  S  and  the  integer,  and  do  not  include  the  angle  brackets 
(<  >  )  in  the  command  line. 

The  string  scrolls  within  the  specified  width,  allowing  you  to  view  and  edit 
the  entire  character  string.  Use  Home,  and  End  to  bring  hidden 

characters  into  view.  When  you  are  entering  data,  the  string  scrolls 
automatically. 

The  M  function  allows  you  to  have  a  list  of  choices  for  a  GET  variable  and 
has  the  following  format: 


FUNCTION  'M  <  list  of  choices  >  ' 
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The  choices  in  the  list  can  be  either  literal  strings  or  literal  numbers  and 
must  be  separated  by  commas.  Since  the  comma  indicates  a  new  choice  in 
the  list,  do  not  specify  choices  with  embedded  commas. 

A  value  appears  in  the  GET  variable  only  when  you  move  the  cursor  to  the 
variable  position. 

The  GET  variable  displays  the  first  item  in  the  list.  Press  the  Spacebar  to  see 
the  remaining  choices  or  until  the  desired  value  appears.  Press  ♦♦  to  select 
an  item  and  move  to  the  next  field. 

You  can  also  select  an  item  by  typing  its  first  letter.  If  items  in  the  list  do  not 
have  unique  first  letters,  the  next  item  matching  the  letter  is  selected. 

If  you  are  in  EDIT  mode,  the  value  currently  stored  in  the  variable  appears 
in  the  field.  Press  Spacebar  to  see  the  next  item  in  the  list.  If  the  current 
item  is  not  an  item  in  the  list,  pressing  Spacebar  displays  the  first  item. 


The  B,  I,  and  J  functions  align  short  fields.  If  you  want  to  trim  a  field  before 
aligning  it,  list  the  T  function  along  with  the  other  three  arguments.  If  you 
specify  no  alignment,  strings  are  left-aligned  and  numbers  right-aligned. 

Templates 

You  form  a  template  by  using  a  single  symbol  for  each  character  to  be  dis¬ 
played  or  input. 

If  you  use  the  R  function  with  a  template  containing  characters  other  than 
template  symbols,  those  characters  are  inserted  into  the  display,  but  not 
stored  as  part  of  the  GET  variable.  If  you  do  not  use  R,  those  characters  are 
displayed  and  are  stored  in  the  GET  variable.  R  applies  only  to  character 
type  variables.  For  numeric  variables,  non-template  symbols  are  always 
inserted  into  the  display  and  never  stored  as  part  of  the  number.  Avoid  using 
non-template  symbols  for  date  and  logical  variables. 
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dBASE  IV  provides  the  following  template  symbols: 


Table  2-3  Picture  template  symbols  used  in  dBASE  IV 


Template 


9 

A 

L 

N 

X 

Y 


Description 

Converts  letters  to  upper  case  and  has  no  effect  on  other 
characters. 

Allows  only  digits,  blanks,  and  signs. 

Displays  the  current  SET  CURRENCY  string  in  place  of  leading 
zeros. 

Displays  asterisks  in  place  of  leading  zeros. 

Displays  if  there  are  digits  to  the  left  of  the  comma. 

Specifies  decimal  position. 

Allows  only  digits  for  character  data.  Allows  digits  and  signs  for 
numeric  data. 

Allows  only  letters. 

Allows  only  logical  data. 

Allows  letters  and  digits. 

Allows  any  character. 

Allows  only  logical  Y,  y,  N,  n.  Converts  y  and  n  to  uppercase 
letters. 


Symbols  !,  #,  9,  A,  N,  and  X  may  be  used  with  SAYs  and  GETs.  Symbols  9,  #, 
A  N,  and  X  prevent  undefined  characters  from  being  input,  but  not  from 
being  displayed. 

If  you  use  a  PICTURE  template  to  GET  a  decimal  number,  you  must  include 
the  decimal  point  in  the  template.  The  template  must  also  leave  room  for  at 
least  one  digit  to  the  left  of  the  decimal  point,  and  leave  room  for  the  sign,  if 
you  want  to  use  the  minus  sign. 


Programming  Notes 

If  you  want  to  use  a  multi-page  format  (.fmt)  file  in  which  the  @...SAY... 
GETs  continue  on  from  2  to  32  pages,  include  a  READ  wherever  you  want  a 
page  break.  The  PgDn  and  PgUp  keys  flip  the  pages.  Multi-page  format  files 
work  only  when  the  .fmt  file  is  opened  with  SET  FORMAT. 
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Tip 

To  design  a  custom  form,  use  CREATE/ MODIFY  SCREEN  to  create  a  format 
file  (.fmt)  that  consists  of  @  commands. 

Activate  the  format  file  with  SET  FORMAT  TO  <  fmt  filename  >  You  can 
append  new  records  or  revise  existing  ones  from  an  .fmt  file  using  any  of  the 
full-screen  editing  commands  such  as  EDIT  and  APPEND. 


Examples 

To  display  the  information  in  the  first  record  of  the  Client  database  file: 

.  USE  Client 
.  CLEW 

.  S  5^0  SAY  TRIMCFirstname)  +  ’  ”  +  Lastrame 

As  you  enter  each  command,  the  resulting  expression  is  displayed  on  your 
screen.  For  a  more  readable  display,  specify  the  spaces  in  quotes  as  part  of 
the  expression,  as  shown  above.  The  results  displayed  on  your  screen  should 
be  the  following: 

Fred  Wriest 

To  provide  a  list  of  choices  that  a  user  may  select  in  a  program  file,  use  the 
@M  PICTURE  function.  To  select  a  day  of  the  week: 

SET  STATU5  O^STATUS  nust  be  cn  fer  the  8.. .GET  fESSJGE.  Oayjfjk  =  "An/  ^ 

3  12,20  SAY  "  Select  the  day  of  the  week  "  GET  Day_pf_yic; 

PICTLRE  "SM  Kri/rue,Ued/[hu,Fri,Sat  Arf  ; 

MESSAGE  "Press  SPACE  to  view  values  and  RETlflN  to  select." 

READ 

In  this  example,  "Any”  is  initially  displayed  in  the  input  field.  As  soon  as  the 
cursor  moves  into  the  field  however,  the  display  changes  to  *Mon',  which  is 
the  first  item  in  the  list.  "Any”  is  never  displayed  again  since  it  is  not  in  the 
list. 

Use  the  VALID  clause  along  with  a  user-defined  function  to  insure  the  integ¬ 
rity  of  input.  Continuing  with  the  previous  example,  enter  an  amount  into  a 
variable  called  Mrate.  Mrate  must  equal  1,  2,  or  3  for  a  weekday,  Saturday, 
or  Sunday,  respectively. 
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Mrate  =  0 

S  14,20  SAY  "The  rate  is  "  GET  l^ate  PICTURE  "91; 
VALID  RcheckO  f€SSAGE  *  " ; 

ERROR  "Weekday  =  1,  Saturday  =  2,  Scnday  =  3* 

READ 

RETURN 

FLNCTICN  Rcheck 
DO  CASE 

C  CASE  Day_crf_vic  O  "S"  .AND.  I^ate  =  1 
RETURN  .T. 

C  CASE  Day_crf_iJc  =  "SatT  .AW.  K-ate  =  2 
RETURN  .T. 

C  CASE  Dey_pf_wk  =  "Suf  .AM),  f^ate  =  3 
RETURN  .T. 

BDCfiSE 
RETURJ  .F. 


In  the  above  example,  the  VALID  condition  calls  the  user-defined  function 
Rcheck().  If  the  validity  of  the  input  is  correct,  Rcheck()  returns  true  (.T.). 
If  Rcheck()  is  false  (.F.),  the  error  message  Weekday  —  1,  Saturday  —  2, 
Sunday  —  3  appears  and  the  user  is  not  allowed  to  exit  the  Held  until  the 
error  is  corrected.  Also  in  the  example,  MESS&jE  is  assigned  a  single  char¬ 
acter  space.  This  is  to  clear  the  MESSAGE  from  the  preceding  @...GET. 


See  Also 

?/??,  APPEND,  CHANGE,  COLO,  CREATE/ MODIFY  SCREEN,  EDIT,  INSERT, 
MODIFY  COMMAND,  PCOL(),  PROW(),  READ,  ROW(),  SET  COLOR,  SET 
CONFIRM,  SET  CURRENCY,  SET  DELIMITERS,  SET  DEVICE,  SET  FIELDS, 
SET  FORMAT,  SET  INTENSITY,  SET  POINT,  SET  SEPARATOR,  SET 
WINDOW  OF  MEMO,  TRAN:iFORM() 
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@... CLEAR  clears  a  portion  of  the  screen. 

Syntax 

@  <  row  1  >  ,<  coll  >  [[CLEAR]  TO  <  row2>  ,<  col2>  ] 

Usage 

<  row  1  >  ,  <  coll  >  are  the  coordinates  of  the  upper  left  corner  of  the  area 
that  you  want  to  clear,  and  <  row2>  ,<  col2>  are  the  coordinates  of  the 
lower  right  corner. 

This  command  erases  the  area  of  the  screen  starting  at  <  rowl  >  ,  <  coll  > 
up  to  and  including  <  row2  >  ,<  col2>  .  If  you  omit  the  CLEAR  TO 

<  row2 >  , <  col2 >  phrase,  the  line  beginning  with  <  rowl  >,<  coll  >  is 
cleared  to  the  end  of  the  line.  If  you  om  it  <  row2  >  ,  <  col2  >  only,  but 
specify  the  CLEAR  keyword,  the  screen  is  cleared  from  <  rowl  >  ,<  coll  > 
to  the  bottom  right  of  the  screen. 


Example 

To  clear  the  area  of  the  screen  from  coordinates  2,9  to  14,39: 
.  a  2,9  CLEAR  TO  1 4^9 

See  Also 

@...FILL,  CLEAR 
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@...FILL  allows  you  to  change  the  colors  of  a  specific  rectangular  region  on 
your  screen. 

Syntax 

@  <  row  1  >  ,<  coll>  FILL  TO  <  row2>  ,<  col2> 

[COLOR  <  color  attribute  >  ] 


Usage 


This  command  changes  the  color  of  the  text  in  the  defined  region. 

<  row  1  >  ,  <  coll  >  are  the  coordinates  of  the  upper  left  corner  of  the 
region,  and  <  row2>  ,<  col2>  are  the  coordinates  of  the  lower  right 


corner. 


In  place  of  <  color  attribute  >  ,  you  must  provide  color  codes  for  the  region. 
These  are  the  same  codes  used  by  SET  COLOR. 

You  may  change  the  standard  foreground  and  background  colors  in  the  area 
only.  This  command  affects  the  display  already  on  the  screen.  Subsequent 
commands  that  write  to  this  area  will  use  the  default  screen  colors,  not  the 
colors  set  with  @...FILL. 

If  you  omit  the  COLOR  option,  @... FILL  clears  the  rectangular  region  of  the 
screen  and  is  equivalent  to  @... CLEAR. 

If  you  specify  coordinates  larger  than  your  screen,  the  Coordinates  are  off 
the  screen  message  appears. 

Example 

To  paint  the  screen  from  coordinates  3,10  to  20,70  in  red  on  black  and  see 
the  text  in  that  region  change  color,  first  issue  a  LIST  MEMORY  command 
to  fill  the  screen  with  text: 

.  list  tea# 

.  S  3,10  FILL  TO  20,70  COLOR  R/N 


See  Also 


SET  COLOR 
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@...TO  draws  a  window  on  the  screen  with  single  lines,  double  lines,  or 
specified  characters.  It  can  also  remove  a  window  from  the  screen. 


Syntax 

@  <  row  1  >  ,<  col  1  >  TO  <  row2  >  ,<  col2> 

[DOUBLE/  PAN  EL/  <  border  definition  string  >  ] 
[COLOR  <  color  attribute  >  ] 


Defaults 

The  default  border  is  a  single  line,  unless  it  has  been  changed  by  the  SET 
BORDER  command. 

The  default  color  is  the  NORMAL  color,  which  can  also  be  changed  by  speci¬ 
fying  the  NORMAL  keyword  of  the  SET  COLOR  command. 


Usage 

<  row  1  >  ,  <  coll  >  are  the  coordinates  of  the  upper  left  corner  of  the  win¬ 
dow,  and  <  row2>  ,<  col2>  are  the  coordinates  of  the  lower  right  corner. 

If  the  row  coordinates  are  the  same,  a  horizontal  line  is  drawn.  If  the  col¬ 
umn  coordinates  are  the  same,  a  vertical  line  is  drawn. 

Defining  a  border  with  the  @...TO  command  options  overrides  the  SET 
BORDER  default  setting. 


Options 

DOUBLE  draws  a  double-line  window  rather  than  the  default  single-  line 
one. 

PANEL  displays  a  solid  highlighted  border.  The  entire  rectangular  border  is 
in  inverse  video. 

<  border  definition  string>  is  a  list  of  character  strings  (or  numbers)  used 
to  define  a  border.  The  character  strings  must  be  delimited,  must  be  sepa¬ 
rated  by  commas,  and  must  appear  in  the  following  order: 

t,  b,l,r,tl,tr,bl,br 
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@...TO 


The  letters  stand  for  the  following  attributes: 


t  -  top 
b  -  bottom 
1  -  left 
r  -  right 


tl  -  top  left  corner 
tr  -  top  right  corner 
bl  -  bottom  left  corner 
br  -  bottom  right  corner 


If  you  specify  only  the  first  attribute  (t),  the  remaining  attributes  default  to 
the  same  value. 


You  omit  an  attribute  by  using  a  comma  in  its  place  if  it  comes  at  the  begin¬ 
ning  of  the  list,  or  by  simply  omitting  it  if  it  comes  at  the  end.  Omitting  an 
attribute  leaves  it  unchanged  from  its  previous  setting. 


If  you  use  numbers  instead  of  character  strings,  use  the  decimal  value  of  the 
character  in  the  IBM  Extended  Character  Set.  Note  that  the  ASCII  code  val¬ 
ues  (decimal  0  through  127)  are  a  subset  of  this  set  (decimal  0  through  255). 
You  may  also  enter  numbers  as  the  argument  of  the  CHR()  function.  The 
numbers  should  not  be  delimited. 

COLOR  —  In  place  of  <  color  attribute  >  ,  you  must  provide  color  codes  for 
either  foreground,  background,  or  both.  These  are  the  same  codes  used  by 
SET  COLOR.  If  you  used  the  PANEL  option,  the  window  will  be  drawn  in  the 
foreground  color  only.  If  you  do  not  provide  color  codes,  this  command  uses 
the  NORMAL  colors  of  the  SET  COLOR  command. 


Programming  Notes 

You  can  use  the  @...TO  command  from  the  dot  prompt  or  in  a  command  or 
format  Hie. 

In  order  to  not  overwrite  the  window  with  a  field  that  is  wider  than  the  win¬ 
dow,  use  the  S  <  n  >  function  of  the  @  command  to  limit  the  size  of  the 
input  area  on  the  screen.  The  S<  n>  function  allows  horizontal  scrolling 
within  the  input  area. 


Example^ 

To  draw  a  double  line  window  from  screen  coordinates  1,10  to  15,40  with 
color  attributes  of  black  on  cyan: 

.  a  1,10  TV  15/40  DCLBLE  COLOR  N/BS 
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You  may  remove  a  window  by  setting  the  first  attribute  to  a  space: 

.3  2^70  12,12’  ’ 


See  Also 

@,  @... CLEAR,  @...FILL,  CHR(),  SET  BORDER,  SET  COLOR 
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ACCEPT 


ACCEPT  is  used  primarily  in  command  files  to  prompt  a  user  for  keyboard 
entry.  It  creates  a  character  memory  variable  in  which  it  stores  the  keyboard 
entry.  Terminate  data  entry  with 


Syntax 

ACCEPT  [  <  prompt>  ]  TO  <  memvar  > 

Usage 

The  <  prompt>  may  be  a  character  type  memory  variable  or  a  character 
string.  If  a  character  string,  it  must  be  delimited  by  single  quotes  (*’),  double 
quotes  or  square  brackets  ([  ]). 

The  keyboard  entry  does  not  require  delimiters:  ACCEPT  treats  all  user  input 
as  character-type  data. 

If  ♦♦  is  entered  in  response  to  the  ACCEPT  command,  the  content  of  the 
memory  variable  is  null  (without  any  contents,  or  ASCII  0). 

A  maximum  of  254  characters  can  be  entered  into  a  variable  with  ACCEPT. 


Programming  Note 

Unless  SET  ESCAPE  is  OFF,  pressing  Esc  in  response  to  an  ACCEPT  will  ter¬ 
minate  a  program. 


Example 

To  prompt  the  user  to  'Enter  your  social  security  number:'  and  store  the 
keyboard  entry  in  the  Ssno  memory  variable: 

.  ACCEPT  " Biter  your  social  sccirity  nurtcrf  TO  Ssro 
Enter  >o_r  axial  searity  nuttw: 


See  Also 

INPUT,  READ,  SET  ESCAPE,  WAIT 
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ACTIVATE  MENU 


This  command  activates  an  existing  bar  menu  and  displays  it  for  use. 


Syntax 

ACTIVATE  MENU  <  menu  name>  [PAD  <  pad  name>  ] 

Usage 

This  command  activates  a  previously  defined  menu  and  displays  it  on  the 
screen  over  any  existing  display.  If  you  use  the  pad  name  with  the  ACT  IVATE 
MENU  command,  the  highlight  bar  appears  in  that  pad.  Otherwise,  the  first 
pad  defined  is  highlighted. 

The  last  activated  menu  is  the  only  active  menu.  Use  the  -*  and  the  —  keys 
to  move  between  the  menu  pads.  You  access  the  pads  in  the  order  in  which 
they  were  defined. 


Example 

„  ACTIVATE  Hsnj  min  PAD  View 

Activates  the  menu  called  Main  and  places  the  cursor  in  the  first  pad  called 
View. 


See  Also 

DEACTIVATE  MENU,  DEFINE  MENU,  MENUQ,  ON  PAD,  PAD(), 
SHOW  MENU 
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ACTIVATE  POPUP 


This  command  activates  a  previously  defined  popup  for  use. 

Syntax 

ACTIVATE  POPUP  <  popup  name> 


Usage 

Only  one  pop-up  menu  can  be  active  at  one  time.  If  you  have  an  active  pop¬ 
up  menu,  it  is  deactivated  when  you  issue  a  subsequent  ACTIVATE  POPUP 
command,  press  or  use  the  DEACTIVATE  POPUP  command. 

Example 

This  command  activates  a  previously  defined  pop-up  menu  which  displays 
some  exit  options: 

.  ACTIVATE  PCRJP  Exitscp 

See  Also 

BAR(),  DEACTIVATE  POPUP,  DEFINE  POPUP,  POPUP(),  PROMPTQ, 

SHOW  POPUP 
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ACTIVATE  SCREEN 
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-H2- ACTIVATE  SCREEN 

ACTIVATE  SCREEN  redirects  an  active  window's  output  to  the  full 
screen,  yet  keeps  that  window  in  the  foreground. 

-H3 -Syntax 

ACTIVATE  SCREEN 

~H3~Usage 

ACTIVATE  SCREEN  gives  you  a  full  screen  display  of  a  window's 
content.  You  do  not  lose  the  active  window's  image,  nor  do  you 
need  to  define  a  window  equal  to  the  coordinates  of  the  full 
screen. 

You  can  use  ACTIVATE  SCREEN  to  keep  a  window's  image  available 
for  reference  while  working  with  full-screen  code.  Pop-up  menus 
also  remain  in  their  correct  relative  positions. 

Although  the  active  window  remains  in  the  foreground,  its  content 
is  not  being  updated.  The  output  it  would  be  delivering  has  beer 
redirected  to  the  full  screen  surrounding  it. 

The  window  remains  on  the  screen  until  deactivated.  If  you  then 
reactivate  the  window,  it  will  cover  any  full  screen  text  that 
occupies  its  position. 

~H3~See  Also 

ACTIVATE  WINDOW,  DEACTIVATE  WINDOW,  DEFINE  WINDOW 
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ACTIVATE  WINDOW 


The  ACTIVATE  WINDOW  command  activates  and  displays  a  defined  window 
from  memory,  and  directs  all  screen  output  to  that  window. 


Syntax 

ACTIVATE  WINDOW  <  window  name  list >  /ALL 

Usage 

To  use  the  ACTIVATE  WINDOW  command,  you  must  have  at  least  one 
defined  window  in  memory.  Only  one  window  can  be  active;  therefore,  if 
you  provide  a  list  of  window  names,  the  last  window  in  the  list  is  the  active 
one. 

When  you  use  the  ALL  option,  all  defined  windows  currently  in  memory  are 
displayed  in  the  order  they  were  defined,  and  the  window  which  was  defined 
last  is  the  active  one.  The  borders  around  each  window  use  the  format  you 
established  when  you  defined  the  window.  If  you  do  not  specify  a  border 
string  when  you  define  the  window,  then  the  SET  BORDER  setting  deter¬ 
mines  the  borders  of  the  window. 

See  Also 

CLEAR  WINDOW,  DEACTIVATE  WINDOW,  DEFINE  WINDOW,  MOVE 
WINDOW,  RESTORE  WINDOW,  SAVE  WINDOW,  SET  BORDER 
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APPEND 


APPEND  allows  you  to  add  new  records  to  the  end  of  the  active  database 
file. 


Syntax 

APPEND  [BLANK] 

Usage 

APPEND  places  you  in  the  full-screen  data  entry  mode.  One  new  record  at  a 
time  is  presented  in  the  default  screen  form  for  data  entry. 

You  terminate  the  process  by  pressing  ■•-*  when  a  new  record  is  presented,  or 
by  pressing  Ctrl-End.  If  you  move  to  a  new  record  and  press  Ctrl-End,  a  blank 
record  is  added  to  the  file. 

The  PgUp  key  moves  the  cursor  to  previous  records,  enabling  you  to  edit 
them.  They  will  be  in  record  order,  not  indexed  order.  The  PgDn  key  moves 
forward  through  the  records,  and  returns  to  the  APPEND  mode  if  you  move 
beyond  the  last  record. 

To  enter  data  into  a  memo  field,  press  Ctrl-Home  or  Ctri-PgDn  when  the  cur¬ 
sor  is  positioned  on  the  memo  field  name.  A  blank  screen  appears  and  text 
can  be  entered.  The  control  keys  are  the  same  as  for  MODIFY  COMMAND.  A 
cursor  control  menu  can  also  be  toggled  on  and  off  with  FI.  To  exit  a  memo 
field,  press  Ctrl-End  (or  Ctrl-W)  to  save  your  entry  in  the  memo  field,  or  press 
Esc  to  abandon  the  entry. 

APPEND  allows  you  to  add  records  to  a  single  database  file  only.  Using  a 
format  file,  it  is  possible  to  @...GET  fields  from  several  related  files.  Using 
APPEND  with  a  format  file  like  this  does  not  add  records  to  unselected  files. 
You  may,  however,  use  the  READ  command  with  the  format  file  to  add  infor¬ 
mation  to  records  in  several  files  simultaneously.  To  add  a  record  to  the  end 
of  the  file,  you  must  first  APPEND  a  BLANK  record  to  the  file,  then  READ. 

Options 

The  BLANK  option  adds  a  blank  record  to  the  end  of  the  database  file,  but 
the  full-screen  mode  is  not  entered.  The  BLANK  record  becomes  the  current 
record. 
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APPEND 


Tips 

All  active  indexes  (including  .mdx  tags)  are  updated  as  records  are 
appended. 

If  SET  AUTOSAVE  is  OFF,  the  directory  entry  for  the  active  database  File  may 
not  reflect  all  new  records  until  the  file  is  closed.  If  SET  AUTOSAVE  is  ON, 
the  directory  on  disk  is  updated  after  each  new  record  is  added. 

Examples 

To  enter  the  full-screen  data  entry  mode  and  begin  APPENDing  records  to 
the  Client  database  file: 

.  SET  STATUS  CN 
.  USE  Client 
.  AFP&O 

To  add  one  record  to  the  Client  database  file  without  entering  the  full-screen 
data  entry  mode: 

.  flFPBOEUNC 

See  Also 

BROWSE,  EDIT,  SET  AUTOSAVE,  SET  CARRY,  SET  FORMAT,  SET  WINDOW 
OF  MEMO 
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APPEND  FROM 


APPEND  FROM  copies  records  from  an  existing  file  to  the  end  of  the  active 
database  file.  The  FROM  file  does  not  have  to  be  a  dBASE  IV  file. 


Syntax 

APPEND' FROM  <  filename>  /? 

[[TYPE]  <  file  typo  ]  [FOR  <  condition  >  ] 


Defaults 

The  filename  must  include  the  drive  designator  if  the  file  is  not  on  the 
default  drive,  unless  a  path  is  set  to  that  drive. 

If  you  do  not  provide  a  file  extension  as  part  of  the  filename,  dBASE  IV 
assumes  a  .dbf  extension. 

If  you  do  not  provide  a  file  extension  as  part  of  the  filename,  but  specify  SDF 
or  DELIMITED,  dBASE  IV  assumes  a  .txt  extension.  Other  file  types  are 
assumed  to  have  the  default  extensions  supplied  by  their  respective  software 
packages. 


Usage 

If  the  FROM  file  is  a  dBASE  IV  database  (.dbf)  file: 

■  Records  marked  for  deletion  are  appended  and  are  not  marked  for  dele¬ 
tion  in  the  active  database  if  SET  DELETED  is  OFF.  If  SET  DELETED  is 
ON,  only  records  not  marked  for  deletion  are  appended. 

■  Only  field  names  found  in  both  files  are  appended.  They  do  not  have  to 
be  in  the  same  order. 

■  Do  not  specify  a  file  type. 

If  a  field  in  the  FROM  file  is  larger  than  the  same  field  in  the  active  database, 
excess  character  data  is  lost,  and  excess  numeric  data  is  replaced  by 
asterisks. 

Options 

The  options  for  <  file  typo  are: 

■  DBASEII  -  dBASE  II  database  file. 
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■  DELIMITED  —  Delimited  Format  ASCII  file.  Data  is  appended  character 
by  character  starting  on  the  left.  Each  record  must  end  with  a  carriage 
return  and  line  feed.  Acomma  separates  each  field  and,  in  addition,  dou¬ 
ble  quotation  marks  surround  character  data  unless  you  specify  another 
delimiter.  This  is  the  same  as  DELIMITED  WITH 

■  DELIMITED  WITH  BLANK  works  with  files  containing  fields  separated 
by  one  space.  No  commas  separate  the  fields,  and  each  record  ends  with 
a  carriage  return  and  line  feed. 

■  DELIMITED  WITH  <  delimiter>  works  with  files  containing  fields  sep¬ 
arated  by  commas  and  character  strings  also  enclosed  in  specified  deli¬ 
miters.  The  default  delimiter  is  the  double  quote  character. 

■  DIF  —  VisiCalc  file  format.  The  VisiCalc  rows  convert  to  records,  and 
the  columns  convert  to  fields. 

■  FW2  —  Framework  II  database  or  spreadsheet  frame. 

■  RPD  —  RapidFile  data  file. 

■  SDF  —  System  Data  Format  ASCII  file.  Data  is  appended  character  by 
character  starting  on  the  left.  Each  record  in  the  FROM  file  is  the  same 
length  and  ends  with  a  carriage  return  and  line  feed,  and  individual 
fields  are  not  delimited. 

■  SYLK  —  MultiPlan  spreadsheet  format  in  row  major  order.  The 
MultiPlan  rows  convert  to  records,  and  the  columns  convert  to  fields. 
dBASE  IV  will  not  APPEND  FROM  a  SYLK  file  saved  in  column  major 
order. 

■  WKS  —  Lotus  1-2-3  spreadsheet  format,  release  1A  The  Lotus  1-2-3  rows 
convert  to  records,  and  the  columns  convert  to  fields.  The  file  begins 
with  the  cell  in  the  upper  left-hand  corner  of  the  spreadsheet. 

■  WK1  —  Lotus  1-2-3  spreadsheet  format,  release  2.x. 

Blank  rows  in  any  spreadsheet  type  are  converted  to  blank  records  in  the 
database  file. 

When  using  APPEND  FROM  to  read  any  of  the  supported  spreadsheet 
formats,  keep  in  mind  that  this  command  expects  the  incoming  data  in  a 
format  that  matches  the  database  file  structure.  This  means  that  you 
should  have  stored  the  spreadsheet  in  row  major  (as  opposed  to  column 
major)  order,  and  that  you  should  remove  column  headers  before 
attempting  to  read  the  data  into  dBASE  IV.  However,  APPEND  FROM 
will  store  row  names  as  long  as  the  database  file  structure  is  designed 
with  them  in  mind.  LOTUS  1-2-3  files  should  not  have  leading  blank  rows 
or  columns.  With  this  type  of  file,  you  should  justify  data  in  the  upper 
left-hand  corner  before  using  APPEND  FROM. 
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Tip 

If  you  are  APPENDing  FROM  a  file  for  which  dBASE  IV  assumes  a  particular 
extension  and  your  file  does  not  have  an  extension,  include  a  period  after  the 
filename. 


Special  Cases 

Use  the  IMPORT  command  to  convert  PFS:FILE  formats  to  dBASE  IV  for¬ 
mat.  You  may  also  use  IMPORT  to  convert  dBASE  II,  Framework  II,  and 
RapidFile  files  to  dBASE  IV  files. 

dBASE  IV  date  fields  can  APPEND  FROM  character  fields,  if  the  data  is  in 
the  proper  date  format.  Conversely,  character  fields  in  the  proper  format  and 
size  can  APPEND  FROM  date  fields.  From  text  files,  dates  can  only  be 
APPENDed  FROM  in  the  form  YYYYMMDD,  not  delimited  (where  YYYY  is 
the  year,  MM  is  the  month,  and  DD  is  the  day). 

Example 

To  APPEND  FROM  a  RapidFile  database  named  Contacts  into  the  Clients 
database  file: 

.  USE  Cl  ients  IWEX  CLeLJvme 
.  AFf&O  FROM  Contacts. rpd  TYPE  RPO 

This  example  opens  Cus_.name.ndx  to  ensure  the  integrity  of  the  index. 
Otherwise,  Cus.name.ndx  would  have  to  be  REINDEXed  the  next  time  you 
open  it. 


See  Also 

COPY,  IMPORT,  SET  DELETEDQ 


JOBNAflE:  PAGE:  34  SESS:  10  Fr  i  riay  6  16:01:47  1988 


®tat  e/d  i  sk2/a  l  l  j  obz/CLS_jnanhat/GRP_manhat/JOB_/nan  I  angref /DI  V_lrchap2a 

APPEND  FROM 
ARRAY 


APPEND  FROM  ARRAY  adds  records  to  a  database  file  from  information  in 
an  array. 


Syntax 

APPEND  FROM  ARRAY  <  array  name>  FOR  <  condition  > 


Usage 

The  contents  of  each  row  in  the  named  array  may  become  a  new  record  in 
the  current  database  file. 

For  each  row  in  the  array,  the  contents  of  tne  first  column  are  replaced  into 
the  first  field,  the  contents  of  the  second  column  are  replaced  in  to  the  sec¬ 
ond  field,  and  so  on.  This  process  continues  until  there  are  either  no  more 
array  columns  or  no  more  fields. 

If  an  array  has  more  columns  than  the  database  has  fields,  the  excess  array 
columns  are  ignored.  If  the  database  file  has  more  fields  that  the  array  has 
columns,  the  excess  fields  remain  empty. 

Each  element  in  the  array  must  be  the  same  data  type  as  the  field  into  which 
it  will  be  replaced. 

If  you  use  the  FOR  clause,  the  condition  is  evaluated  before  each  row  in  the 
array  is  added  to  the  database  file.  A  row  is  APPENDed  only  if  the  condition 
evaluates  to  true  (.T.).  If  the  condition  is  false  (.F.),  the  row  is  skipped  and 
the  next  row  is  processed. 

You  must  DECLARE  the  arrty  and  STORE  information  to  its  elements  before 
you  can  APPEND  from  it.  If  the  array  does  not  exist,  the  message  Array  not 
declared  appears. 


Programming  Notes 

The  APPEND  command  gives  the  user  access  to  all  records  in  a  database  file. 
You  may  use  arrays  to  hold  information  entered  from  the  keyboard,  and  then 
APPEND  the  information  into  a  database  file,  rather  than  allow  the  user  to 
have  access  to  all  information  contained  in  the  file  with  APPEND. 
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APPEND  FROM  ARRAY 


Example 

To  APPEND  FROM  an  ARRAY  into  the  TVansact  database  file,  first  establish 
the  array: 


rujuui  _ 

.  NadataClyZJ  =  Q59-1CI&) 
88-Id) 


.  NendataClsS]  =  DA7EO 

03/01/87 

.  NeudataClyAJ  =  .F. 

.F. 

.  NodataCI^J  =  125.00 
125.00 
.  USE  Transact 
.  APPEND  FROM  ARRAY  Neudata 
^TJ  record  added 


See  Also 

APPEND,  COPY  TO  ARRAY,  DECLARE,  STORE 
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APPEND  MEMO 


APPEND  MEMO  imports  a  file  into  a  named  memo  field. 


Syntax 

APPEND  MEMO  <  memo  field  name>  FROM  <  filename  >  [OVERWRITE] 


Defaults 

If  you  do  not  specify  a  filename  extension,  the  default  extension  .txt  is 
assigned. 


Usage 

APPEND  MEMO  can  read  any  file  into  a  memo  field,  including  object  (.dbo) 
files.  The  entire  file  is  read  and  added  to  the  existing  text  in  the  memo  field. 

Use  the  OVERWRITE  option  to  erase  the  existing  text  before  adding  the  new 
text  to  the  memo  field. 

If  the  named  field  cannot  be  found,  the  message  Field  not  found  appears. 

If  the  named  field  is  not  a  memo  field,  the  message  Field  must  be  a  memo 
field  appears. 

If  the  specified  filename  cannot  be  found,  the  message  File  does  not  exist 
appears. 


Examples 

To  APPEND  a  text  file  named  Newtext.txt  to  the  first  record  in  the  Client 
database  file,  first  create  the  text  file  with  the  MODIFY  FILE  command: 

.  MODIFY  FILE  Newfile.  txt 
New  text  begins  here... 
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Save  the  file  with  Ctrl-End.  Then,  from  the  dot  prompt: 

.  LSE  CL  Lent 

.  ?  ClienJtist 

85-200  08/02/85 

C-3Q0-4Q0  BOCK  CASE  535.00  1 

.  A PF&D  MEKJ  CL  ienJiist  FROM  Neufile 

.  ?  CL  ienJiist 


See  Also 


COPY  MEMO,  MODIFY  COMMAND/ FILE 
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ASSIST 


ASSIST  gives  you  access  to  dBASE  IV’s  Control  Center. 

Syntax 

ASSIST 


ASSIST  brings  you  to  the  Control  Center,  from  which  you  can  reach  the  dif¬ 
ferent  parts  of  dBASE  IV’s  Menu  System. 

The  Control  Center  always  opens  a  catalog.  It  first  attempts  to  open  the  most 
recently  opened  catalog  in  the  master  catalog.  If  a  catalog  is  not  available,  it 
creates  a  new  catalog  called  Untitled.cat. 

To  begin  using  the  Menu  System,  follow  the  instructions  on  the  screen. 

The  Control  Center  is  a  gateway  to  six  design  screens,  each  represented  by  a 
panel  in  the  Control  Center.  These  design  screens  can  also  be  reached  using 
the  CREATE,  CREATE/ MODIFY  QUERY/VIEW,  CREATE/ MODIFY  SCREEN, 
CREATE/ MODIFY  REPORT,  CREATE  MODIFY  LABEL,  and  CREATE/ 
APPLICATION  commands.  *  A 

You  may  also  view,  edit,  and  add  data,  as  with  BROWSE,  EDIT,  and 
APPEND;  run  reports  and  labels,  as  with  REPORT  FORM  and  LABEL  FORM; 
execute  programs  and  other  files,  as  with  DO,  SET  VIEW,  and  SET  FORMAT; 
and  enter  the  program  editor,  as  with  MODIFY  COMMAND/FILE. 

To  leave  the  Control  Center  and  return  to  the  dot  prompt,  press  Esc;  or,  you 
can  press  Alt-^)to  open  the  Enit  menu,  then  select  the  Exit  to  dot  prompt 
option. 


See  Also 

The  Control  Center  is  described  in  Learning  dBASE  IV and  in  Using  the  Menu 
System.  Please  refer  to  these  manuals  for  more  information. 

APPEND,  BROWSE,  CREATE,  CREATE/ MODIFY  APPLICATION,  CREATE 
MODIFY  LABEL,  CREATE/MODIFY  QUERY/ VIEW,  CREATE/ MODIFY 
REPORT,  CREATE/ MODIFY  SCREEN,  DO,  EDIT,  LABEL  FORM,  MODIFY 
COMMAND/ FILE,  REPORT  FORM,  SET  FORMAT,  SET  VIEW 
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AVERAGE 


AVERAGE  com  putes  the  arithmetic  mean  of  numeric  expressions. 


Syntax 


AVERAGE  [  <  expN  list  >  ]  [<  scope  >  ]  [FOR  <  condition  >  1 

[WHILE  <  condition  >  ]  [TO  <  memvar  list  >  /TO  ARRa5|<  array 
name  >  ] 

Defaults 

All  records  are  averaged  unless  otherwise  specified  by  the  scope  or  the  FOR 
or  WHILE  clause.  All  numeric  fields  are  averaged  unless  otherwise  specified 
by  an  expression  list.  The  result  of  AVERAGE  is  displayed  on  the  screen  as 
long  as  SET  TALK  is  ON. 


Usage 


If  you  use  the  TO  ARRAY  phrase,  the  array  must  be  one-dimensional.  The 
results  are  stored  in  the  named  array,  in  order  beginning  with  the  first  slot. 
If  there  are  more  results  than  the  original  array  declaration,  the  excess 
results  are  not  stored.  If  there  are  fewer  results,  the  remaining  array 
elements  remain  unchanged. 


Example 

To  obtain  the  average  Total_bill  for  Client_id  C00002  in  the  Transact  data¬ 
base  file: 


2  reoonds  averaged 
TotaLbill 

712.50 


See  Also 

CALCULATE,  DECLARE,  SET  HEADING,  SET  TALK,  SUM 
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BEGIN  TRANSACTION/ 
END  TRANSACTION 


This  two-phase  command  starts  a  transaction,  records  changes  made  to  a 
database  file,  and  provides  the  option  to  ROLLBACK  those  changes.  The  sec¬ 
ond  phase  of  the  command  commits  to  the  changes  and  removes  the  option 
to  ROLLBACK. 

Syntax 

BEGIN  TRANSACTION  [  <  path  name  >  ] 

and  when  the  transaction  is  complete  and  satisfactory: 

END  TRANSACTION 

Usage 

You  can  use  this  commmand  in  a  program  or  from  the  dot  prompt  to  start  a 
transaction  recording  the  changes  you  make  to  records  in  a  database  file. 

A  process  that  modifies  a  single  record  in  a  database  is  referred  to  as  an 
atomic  action.  Atomic  actions  are: 

■  Adding  new  records 

■  Changing  the  data  in  records 

■  Changing  the  delete  status  of  records 

BEGIN  TRANSACTION  starts  recording  these  atomic  changes  in  a  transac¬ 
tion  log  file  which  it  creates.  The  transaction  log  file  is  named  TVanslog-log 
on  a  standalone  system,  and  <  Workstation  name>  .log  on  a  local  area  net¬ 
work.  <  Workstation  name  >  is  the  name  of  the  computer  that  starts  the 
BEGIN  TRANSACTION  command  on  the  network.  Specify  a  path  name  if 
you  want  the  log  file  in  a  specific  directory;  otherwise,  it  will  be  created  in 
the  current  directory. 

In  addition  to  the  transaction  log  file,  BEGIN  TRANSACTION  sets  the  integ¬ 
rity  tag  located  in  the  database  file  header  to  indicate  that  the  file  is  in  a  state 
of  change. 

If  you  decide  to  ROLLBACK  from  the  changes  you  made,  then  this  log  file  is 
read  to  restore  the  database  file  to  its  unchanged  state.  While  a  transaction  is 
active,  before  you  issue  an  END  TRANSACTION  command,  you  can  undo  all 
unwanted  changes.  Use  the  ROLLB^K  command  to  restore  the  database 
file  to  its  pre-transaction  state. 

If  the  change  is  satisfactory,  issue  an  END  TRANSACTION  command.  This 
command  terminates  the  active  transaction,  deletes  the  transaction  log  file, 
and  clears  the  integrity  tag  from  the  database  file  header. 
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BEGIN  TRANSACTION/END  TRANSACTION 


You  should  not  use  this  command  until  you  are  certain  that  the  transaction 
has  done  what  you  wanted  it  to  do.  Once  you  issue  an  END  TRANSACTION 
command  and  the  transaction  log  file  is  erased,  the  only  way  to  restore  the 
database  file  to  its  pre-transaction  state  is  to  use  backup  files. 

A  transaction  must  be  complete  and  the  log  file  deleted  before  you  can  start 
another  transaction;  transactions  cannot  be  nested.  To  perform  several  trans¬ 
actions  in  succession,  bracket  each  transaction  within  a  BEGIN 
TRANSACTION  and  an  END  TRANSACTION  command.  Both  BEGIN 
TRANSACTION  and  END  TRANSACTION  must  be  contained  in  the  same 
procedure  file. 

Transaction  Recording 

A  group  of  dBASE  IV  commands  that  change  database  files  or  the  operating 
environment  are  recorded  in  the  Transaction.log  file.  These  commands  cause 
atomic  changes,  update  catalogs,  or  create  new  database  or  index  files. 
dBASE  IV  commands  that  create  new  files  are  allowed  in  transactions  unless 
these  commands  overwrite  existing  files  or  close  open  files.  Overwriting  exist¬ 
ing  files  or  closing  open  files  is  not  allowed,  as  this  would  make  ROLLBACK 
impossible. 

dBASE  IV  commands  that  cause  atomic  actions  to  database  files  are: 

APPEND 

BROWSE 

CHANGE 

DELETE 

EDIT 

RECALL 

REPLACE 

UPDATE 

dBASE  IV  commands  that  create  new  files  are  allowed  during  transaction 
processing  if  they  do  not  close  open  files.  These  are: 

COPY  [STRUCTURE]  TO  <  new  file  >  [EXTENDED] 

CREATE  <  new  file  >  [FROM  <  filename  >  ] 

IMPORT  FROM  <  filename> 

INDEX. ..TO  <  new  file  > 

JOIN. ..TO  <  new  file  > 

SET  CATALOG  TO  <  new  file  > 

SORT.. .TO  <  newfile> 

TOTAL.. .TO  <  new  file  > 

Some  of  the  same  commands  that  are  allowed  when  they  create  new  files  are 
not  allowed  during  a  transaction  if  they  close  open  files. 
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BEGIN  TRANSACTION/END  TFIA NSACTION 


These  commands  are: 

CREATE  [FROM] 
INDEX  ON 
SET  CATALOG  TO 
SET  INDEX  TO 
USE 


Commands  Not  Allowed  in  Transactions 


The  following  dBASE  IV  commands  are  never  allowed  during  a  transaction: 
CLEAR  ALL 

CLOSE  ALL/ DATABASE/ INDEX 

DELETE  FILE 

ERASE 

INSERT 

MODIFY  STRUCTURE 

PACK 

RENAME 

ZAP 


Attempting  to  use  any  of  these  commands  during  a  transaction  results  in  an 
error  message. 

The  UNLOCK  command  is  a  special  case;  while  it  does  not  produce  an  error 
message,  it  has  no  effect  during  a  transaction. 


Tip 

Back  up  database  Hies  that  are  going  to  be  involved  in  transactions.  In  case 
you  do  not  like  the  changes  you  made,  and  the  ROLLBACK  command  is  not 
successful  in  restoring  the  files  to  their  beginning  state,  you  can  use  the 
backup  copies  to  undo  the  transaction  manually. 


Example 

If  you  purchased  dBASE  IV  Developer’s  Edition,  please  see  the  Networking 
with  dBASE /V manual. 


See  Also 

COMPLETEDQ,  ISMARKEDQ,  RESET,  ROLLBACK,  ROLLBACK!) 
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BROWSE 


BROWSE  is  a  full-screen,  menu-assisted  command  for  editing  and  appending 
records  in  database  (.dbf)  files  and  views. 


Syntax 


BROWSE  [NOINIT]  [NOFOLLOW]  [NOAPPEND]  [NOMENU]  [NOEDIT] 
[NODELETE]  [NOCLEAR]  [COMPRESS]  [FORMAT]  [LOCK  <  expN>  ] 
[WIDTH  <  expN >  ]  [FREEZE  <  field  name>  ][WINDOW 
<  window  name  >  ] 


/<  calculated  field  2  >  —  <  expression  2> 

Defaults 

If  a  database  file  is  not  in  USE  before  you  BROWSE,  the  command  will 
prompt  you  to  enter  a  database  filename. 

Calculated  fields  are  always  read-only. 


Usage 


BROWSE  displays  records  from  database  files  or  views  in  tabular  form.  All 
fields  are  displayed  in  the  order  specified  by  the  file  structure  or  view  defini¬ 
tion,  or  in  the  order  listed  after  the  FIELDS  option.  If  the  files  have  been 
PROTECTed,  the  fields  must  also  have  a  read/write  or  read-only  attribute. 

You  can  change  from  BROWSE  to  EDIT  by  pressing  the  F2  Data  key. 

You  can  edit  all  fields  except  calculated  fields  or  read-only  fields.  When  you 
move  the  cursor  to  a  field  that  can  be  edited,  the  field  appears  in  enhanced 
video.  The  cursor  also  indicates  where  you  can  make  changes  in  the  field.  If 
the  changes  you  make  affect  any  calculated  fields,  the  calculated  fields  are 
recalculated  and  redisplayed. 

If  an  index  file  is  active,  editing  a  key  field  value  repositions  the  record 
according  to  its  new  key  value  in  the  index. 

You  can  also  add  records  to  the  active  file  or  view.  Move  the  cursor  to  the 
bottom  of  the  file  and  press  |.  A  prompt  asks  if  you  want  to  add  records  to 
the  file.  If  you  answer  Y,  BROWSE  goes  to  APPEND  mode  and  allows  you  to 
add  a  record  to  the  file.  You  can  also  add  records  to  the  database  files  con¬ 
tained  in  a  view. 
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BRCWSE 


Press  F10  to  activate  the  BROWSE  menu  bar.  The  BROWSE  menus  are 
described  fully  in  Learning  dBASE  IV and  Using  the  Menu  System.  Please 
refer  to  these  manuals  for  more  information. 


Options 

NOINIT  allows  the  command  line  options  that  you  used  with  a  previous 
BROWSE  command  to  be  used  in  the  current  EDIT.  NOINIT  instructs  the 
BROWSE  command  not  to  initialize  the  BROWSE  table,  but  to  use  the  table 
from  the  most  recent  BROWSE  instead. 

NOFOLLOW  affects  only  indexed  files.  Ordinarily,  editing  a  key  field  value 
repositions  the  record  according  to  its  value  in  the  index,  and  the  record 
remains  the  current  one.  If  you  issue  NOFOLLOW  before  changing  the  field’s 
contents,  the  record  is  repositioned,  but  the  record  that  took  its  original 
place  in  the  file  order  becomes  the  current  record. 

NOAPPEND  keeps  you  from  adding  new  records  to  the  current  file  when  in 
BROWSE  mode. 

NOMENU  prevents  access  to  the  menu  bar. 

NOEDIT  makes  all  fields  in  the  table  read-only.  Using  this  option  means  that 
no  records  can  be  edited  in  BROWSE  mode.  You  can  still  add  records  to  the 
file.  You  can  also  mark  records  for  deletion. 

NODELETE  prevents  you  from  deleting  records  by  pressing  Ctrt4j)when  in  \4  ^  7“  /ye) 

BROWSE  mode.  X - - - 

NOCLEAR  leaves  the  BROWSE  table  on  the  screen  after  you  exit  BROWSE. 

COMPRESS  slightly  reduces  the  table  format  to  allow  two  more  lines  of  data 
to  appear  on  the  screen.  The  ;olumn  headings  are  placed  on  the  top  line  of 
the  table  border,  and  no  line  separates  the  headings  from  the  data.  BROWSE 
presents  up  to  17  records  on  a  screen  if  you  don’t  use  the  COMPRESS 
option,  but  up  to  19  records  with  COMPRESS. 

FORMAT  instructs  BROWSE  to  use  the  @  command  options  specified  in  the 
active  format  (.fmt)  file.  All  @  command  options  except  the  positioning  of 
fields  on  the  screen,  which  is  controlled  by  the  @  command’s  row  and  col¬ 
umn  coordinates,  are  then  used  by  BROWSE.  Row  and  column  coordinates 
are  ignored,  because  BROWSE  always  positions  fields  in  a  table  on  the 
screen. 
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LOCK  specifies  the  number  of  contiguous  fields  on  the  left  of  the  screen  that 
do  not  move  when  you  are  scrolling  the  BROWSE  table.  When  you  press 
Ctrl—*  or  Ctrl--*-  to  scroll  fields  left  or  right,  the  number  of  fields  you  locked 
will  remain  displayed  in  the  same  position  on  the  screen. 

LOCK  0  will  undo  all  locked  fields. 

WIDTH  sets  an  upper  limit  on  the  column  widths  for  all  fields  in  the 
BROWSE  table.  The  specified  WIDTH  overrides  the  width  defined  by  the 
database  structure.  If  both  WIDTH  and  the  <  column  width  >  option  are 
used  for  a  field,  the  smaller  value  of  the  two  will  take  precedence. 

The  WIDTH  option  does  not  apply  to  memo  fields  or  logical  fields.  Numeric 
and  date  fields  will  not  display  in  a  column  WIDTH  that  is  less  than  the 
width  of  these  fields  in  the  database  file  structure. 

FREEZE  confines  you  to  one  field  or  column  in  the  file.  If  the  field  has  been 
made  read-only,  you  may  not  edit  it.  All  other  fields  in  the  field  list  or  data¬ 
base  file  table  remain  on  the  screen,  but  cannot  be  edited. 

FREEZE  without  a  field  name  will  undo  a  previously  established  FREEZE. 

WINDOW  activates  a  window  which  then  defines  an  area  on  the  screen  used 
by  the  BROWSE  table.  The  rest  of  the  screen  remains  intact.  When  you  exit 
BROWSE,  the  window  is  automatically  deactivated,  unless  you  also  used  the 
NOCLEAR  option. 

FIELDS  allows  you  to  choose  fields  and  specify  the  order  in  which  they 
appear  in  the  table.  If  the  file  or  view  is  PROTECTed  and  you  do  not  have 
access  to  a  field,  it  is  not  displayed.  The  FIELDS  option  also  allows  you  to 
designate  a  field  as  read-only,  and  to  construct  and  name  calculated  fields 
that  will  appear  in  the  BROWSE  table. 

Each  calculated  field  is  composed  of  an  assigned  field  name  and  an  expres¬ 
sion  that  results  in  the  calculated  field  value,  as  Commission  =* 

Ra  re  *SaIeprice. 

The  field  name  you  assign  becomes  the  column  header  for  the  calculated 
field  in  the  BROWSE  table.  dBASE  IV  determines  the  length  of  a  calculated 
field  after  evaluating  the  expression  in  the  first  record. 

The  / R  option  makes  a  field  read-only.  The  read-only  flag  set  by  PROTECT 
has  precedence  over  this  option. 

The  <  column  width  >  option  is  a  numeric  expression  that  defines  the  col¬ 
umn  width  of  a  field  and  can  be  used  with  each  field  in  the  fields  list.  It  must 
be  preceded  by  a  slash  (/)  in  the  command  line. 
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BROWSE 


<  column  width  >  can  be  a  value  from  4  to  100  for  character  fields,  and 
from  8  to  100  for  date  and  numeric  fields. 

<  column  width  >  is  ignored  for  memo  fields  and  logical  fields.  It  is  also 
ignored  if  it  is  larger  than  the  WIDTH  option,  or  if  the  value  is  less  than  the 
database  file  structure’s  width  for  date  or  numeric  fields. 


Tip 

If  SET  AUTOSAVE  is  OFF,  the  directory  entry  for  the  active  database  file  may 
not  reflect  all  new  records  until  the  file  is  closed.  If  SET  AUTOSAVE  is  ON, 
the  directory  on  disk  is  updated  after  each  new  record  is  added. 


Examples 


In  a  program  file  use  BROWSE  to  display  up  to  seven  records  from  the 
Transact  database  file.  Limit  the  size  of  the  display  to  seven  records  by 
declaring  a  window  called  Partial.  Filter  the  database  file  for  orders  that 
occurred  in  March.  Allow  the  user  to  move  within  the  BROWSE  table,  but 
not  to  make  changes  to  the  database  file.  Finally,  leave  the  BROWSE  table  on 
the  screen  while  another  routine  utilizes  the  lower  portion  of  the  screen. 
Leaving  the  table  on  the  screen  allows  the  user  to  see  the  data. 

USE  TRANSACT  / 

SET  FILTER  TO  WNTH(Date_ir«ru)  =  3T&  Filter  for  torch. 

SKIP  <£8&  Evaluate  the  first  record 

GO  TCP  ^.8 &  against  the  filter. 

DEFINE  WINDOW  Partial  FROM  2,10  TO  9/0 

BROWSE  NQAPPBO  NCEDIT  NCDELFE  N0CLEAR  NX©U  COTRESS  WINDOW  Partial 
DO  Next_prg 


* 
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BRCWVSE 


The  BROWSE  command  in  the  example  creates  a  display  like  the  following: 


pCLIENT_II> 

rORDER  I  Eh 

'DATE  TRANSi 

'INVOICED] 

'TOTAL  BILL] 

L00001 

87-109 

03/09/87 

T 

415,00 

C0000Z 

87-110 

03/09/87 

T 

175.00 

L0000Z 

87-111 

03/11/87 

F 

1000.00 

L00001 

87-1 1Z 

03/Z0/87 

T 

700.00 

A 00005 

87-113 

03/Z4/87 

T 

1Z5.00 

B1Z000 

87-114 

03/30/87 

F 

450.00 

Tech  Reuieu  Screen  Shot  (xZ05) 


Figure  2-1  BROWSE  Window  {{Include  a  screen  shot  here.  See  attached  for 
sample.}} 


See  Also 

APPEND,  EDIT,  PROTECT,  SET  MEMOWIDTH,  SET  REFRESHES ET 
WINDOW  OF  MEMO 
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CALCULATE 


CALCULATE  computes  financial  and  statistical  functions  with  your  data. 


Syntax 

CALCULATE  [scope]  <  option  list> 

[FOR  <  condition  >  ]  [WHILE  <  condition  >  ] 

[TO  <  memvar  list >  /TO  ARRAY  <  array  name>  ] 

where  <  option  list >  can  be  any  one  of  the  following  functions: 

AVG(  <  expN  >  ) 

CNT() 

MAX(<  exp>  ) 

MIN(<  exp>  ) 

NPV(<  rate  >  ,<  flows  >  ,<  initial  >  ) 

STD(  <  expN  >  ) 

SUM(<  expN  >  ) 

VAR(<  expN  >  ) 


Default 

All  records  in  the  active  file  are  processed  if  a  scope  is  not  defined. 


Usage 

The  CALCULATE  command  handles  all  records  in  the  active  database  file 
until  the  scope  is  completed  or  the  WHILE  condition  is  no  longer  true.  The 
result  of  the  command  is  one  or  more  type  N  numbers. 

If  you  include  a  FOR  clause,  each  record  is  evaluated  and,  if  true  (  T.),  the 
specified  functions  are  evaluated  and  performed. 

If  you  include  the  TO  ARRAY  option,  the  results  are  stored  in  the  named 
array  which  must  be  one-dimensional.  The  array  slots  are  filled  in  order 
beginning  with  the  first  one. 

If  SET  TALK  is  ON,  the  results  appear  on  the  screen.  If  SET  HEADING  is  ON, 
the  results  are  also  labeled  with  the  name  of  the  function  and  the  field  name. 


Options 

The  financial  and  statistical  optional  functions  are  described  below.  You  can 
save  the  results  of  these  options  with  the  TO  option. 
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CALCULATE 


NOTE 

Records  with  blank  values  are  used  in  calculating  the  maximum,  and 
are  treated  as  Helds  that  are  equal  to  zero.  To  ignore  a  blank  cash 
flow,  for  example,  use  .NOT.  IS  EMPTY (’  flows’)  in  the  FOR  condition. 


AVG(<  expN  >  )  calculates  the  arithmetic  mean  of  the  values  in  a  particular 
database  field.  It  returns  a  number  that  is  the  same  data  type  as  the 
argument. 

CNT()  counts  the  records  in  a  database  File.  The  FOR  condition  is  evaluated 
for  each  record.  If  the  condition  is  true  (.T.),  the  record  count  is  increased 
by  one. 

MAX(<  exp>  )  determines  the  largest  number  in  a  particular  database  field. 

<  exp>  is  a  numeric,  date,  or  character  expression  that  will  normally  be 
the  name  of  a  field,  or  an  expression  involving  the  name  of  a  field. 

MIN(<  exp  >  )  determines  the  minimum  number  in  a  particular  database 
field.  Use  it  in  the  same  manner  you  would  use  MAX(),  except  you  will 
determine  a  minimum  value. 

NPV(  <  rate  >  ,  <  flows  >  ,  <  initial  >  )  calculates  the  net  present  value  of 
the  specified  database  field. 

<  rate  >  is  the  discount  rate  represented  by  a  decimal  number. 

<  flows  >  is  a  series  of  signed  (+  /—  )  periodic  cash  flow  values.  If 

<  initial  >  is  not  used,  the  series  begins  with  the  present  period.  <  flows  > 
can  be  any  valid  numeric  expression,  but  will  normally  be  the  name  of  a 
field,  or  an  expression  involving  the  name  of  a  field. 

<  initial >  is  a  numeric  expression  whose  value  represents  an  initial  invest¬ 
ment.  The  initial  value  should  be  a  negative  number  since  it  represents  cash 
outflow. 

STD(<  expN  >  )  calculates  the  standard  deviation  of  the  values  in  a  database 
field.  The  formula  for  the  standard  variation  is  the  square  root  of  the  vari¬ 
ance.  <expN>  is  a  numeric  expression  that  will  normally  be  the  name  of  a 
field,  or  an  expression  involving  the  name  of  a  field.  It  returns  a  Type  F 
number. 

SUM(<  expN>  )  determines  the  sum  of  the  values  in  a  particular  database 
field.  The  FOR  condition  is  evaluated  for  each  record.  If  the  condition  is 
true,  the  value  for  that  record  is  added  to  the  previous  total.  <  expN  >  is  a 
numeric  expression  that  will  normally  be  the  name  of  a  field,  or  an  expres¬ 
sion  involving  the  name  of  a  field. 
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CALCULATE 


VAR(<  expN  >  )  calculates  the  population  variance  of  the  values  in  a  particu¬ 
lar  database  filed.  <  expN  >  is  a  numeric  expression  that  will  normally  be 
the  name  of  a  field,  or  an  expression  involving  the  name  of  a  field.  The  out¬ 
put  of  VAR()  is  a  Type  F  number. 


Examples 

To  find  the  sum  of  all  invoiced  orders  in  the  Transact  database  file: 


.  USE  Transact 

.  CALCULATE  FOR  Invoiced  SLMCTotaLbilU,  CNTO  TO  total,  cnt 

~5LH(TotaLt>ill)  CNTO _ _ 

- '  6955  .CD  8-ffl  I 

.  ?  ’7he  indeed  erders  total  FtLTRH1(SW(total 

The  8  invoiced  orders  total  $6965.00 


To  calculate  the  average  bill  and  the  standard  deviation  of  the  Total.bill 
field: 


„  USE  Transact 

.  CALCULATE  STDCTotaLbill),  MSCTotaLbill)  TO  deviate,  average 
~STDC7otaLbill)  AMSCTotaLbill) 

- 1  555.92  sgrm  1 


.  deviate  =  L  TRIM(STR(deviateJ$^)) 

555.92 

.  average  =  LTRIMCSTRCaverage, ,8,2)) 

840.00 

.  ?  fThe  average  bill  is  Shaver-age*-4  with  a  deviation  of  $4*deviate^J^*-4.  4 
The  average  bill  is  $840.00  with  a  deviation  of  $555.92.  A 


To  find  the  last  date  that  a  transaction  took  place  and  the  largest  order  to 
date: 


.  LBE  Transact 

.  CAWjLATE  MflX(Datz_trars),  WXCTotaLbill)  TO  lastJrans,  largest 
~~M(tete_trans)  MAX(TotaLbill) 

'  Wiofa  1850.CD 

.  SET  CBmjRTCN 

.  ?  4The  Last  order  ujs  cn  '  +  DMTdastjrans)  +  ' 

The  last  order  was  cn  10  Apri  l  1987. 

.  ?  Vbe  largest  order  has  L  TR1/KSTR (largest^)  +  '.4 

The  largest  order  was  $1850.00. 
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The  CALL  command  allows  you  to  call  binary  file  program  modules  loaded 
in  memory.  You  must  have  first  loaded  the  binary  program  files  in  memory 
using  the  LOAD  command. 

Syntax 

CALL  <  module  name>  [WITH  <  variable  >  ] 


Usage 

The  CALL  command  executes  a  binary  program  file  that  has  been  loaded  in 
memory  with  the  LOAD  command.  dBASE  IV  treats  each  loaded  file  as  a 
subroutine  or  module  rather  than  as  an  external  program  (which  could  be 
executed  with  the  RUN  command).  As  a  result,  each  time  you  want  to  exe¬ 
cute  the  program,  it  can  simply  run  from  memory  without  having  to  be 
reloaded  from  a  disk.  Up  to  16  binary  program  files  can  be  loaded  in  mem¬ 
ory  at  one  time,  and  each  can  be  up  to  32,000  bytes  long. 

When  you  CALL  the  binary  program  file,  you  specify  the  name  of  the  file 
without  the  .bin  extension.  When  you  call  the  file,  you  can  pass  either  a  char¬ 
acter  expression,  a  memory  variable,  or  an  array  element  of  any  data  type  to 
the  binary  program  file.  All  character  type  memory  variables  and  expressions 
end  with  a  null  (ASCII  value  of  zero). 

When  the  program  module  is  called,  the  Code  Segment  (CS)  points  in  mem¬ 
ory  to  the  beginning  of  the  module.  The  Data  Segment  (DS)  and  BX  registers 
contain  the  address  of  the  first  byte  of  the  memory  variable,  field,  array  ele¬ 
ment,  or  character  expression. 


Options 

The  WITH  option  is  a  character  expression,  field  name,  memory  variable  (or 
array  element),  or  field  name.  Memory  variables,  fields,  and  elements  can  be 
of  any  type.  Character  expressions  are  called  by  value,  but  all  other  param¬ 
eters  are  called  by  name. 

Example 

See  the  LOAD  command. 

See  Also 

CALL(),  LOAD,  RELEASE,  RUN/! 
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CANCEL 


CANCEL  stops  the  execution  of  a  command  file,  closes  all  open  command 
files,  and  returns  dBASE  IV  to  the  dot  prompt.  CANCEL  does  not  close  pro¬ 
cedure  files. 

Syntax 

CANCEL 


Usage 

dBASE  IV  ignores  any  text  on  lines  in  a  dBASE  program  file  following 
CANCEL. 


Example 

To  stop  command  processing  when  an  error  is  found,  include  CANCEL 
within  an  IF...ENDIF  or  DO  CASE. . .ENDCASE  structure.  In  the  following 
example,  the  Merror  memory  variable  was  previously  established: 

8&  If  error  is  true,  oamsnd 
8&  file  execution  is  cancelled. 


IF  Merror 
^CEL 
MIF 


See  Also 

RESUME,  RETRY,  RETURN,  SET  REPROCESS,  SUSPEND 
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CHANGE 


CHANGE  is  an  alternate  syntax  for  EDIT,  a  full-screen  command  you  use  to 
display  or  change  the  contents  of  a  record  in  the  active  database  file  or  view 

Syntax 

CHANGE  [NOINIT)  [NOFOLLOW]  [NOAPPEND]  [NOMENU]  [NOEDIT] 

[NODELETE]  [NOCLEAR]  [<  record  number >  ]  [HELDS  <  field  list >  ] 
[<  scope  >  ]  [FOR  <  condition  >  ]  [WHILE  <  condition  >  ] 

Usage 

The  CHANGE  command  is  identical  to  the  EDIT  command.  See  EDIT  for 
further  information  about  how  to  use  this  command. 

See  Also 

EDIT 
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CLEAR 


CLEAR  erases  the  screen,  repositions  the  cursor  to  the  lower  left-hand 
corner  of  the  screen,  and  releases  all  pending  GETs  created  with  the 
@  command. 

Various  forms  of  the  CLEAR  command  also  close  database  files;  release 
memory  variables,  field  lists,  windows,  popups,  and  menus;  and  empty  the 
type-ahead  buffer. 

Syntax 

CLEAR  [ALL/ FIELDS/ GETS/ MEMORY/ MENUS/ POPUPS/TYPEAHEAD 
/WINDOWS] 

Usage 

You  must  use  the  CLEAR  command  either  without  any  options,  or  with  one 
option  only.  You  may  not  use  more  than  one  option  in  a  command  line. 


Options 

ALL  closes  all  open  database  files;  releases  all  memory  variables  (except  sys¬ 
tem  variables),  array  elements,  popup  and  menu  definitions;  and  selects 
work  area  1.  Closing  the  database  files  also  closes  their  associated  index 
(both  .ndx  and  .mdx)  files,  format  (.fmt)  files,  and  memo  (.dbt)  files.  CLEAR 
ALL  also  closes  the  catalog  (.cat)  file  if  one  is  active. 

FIELDS  releases  the  fields  list  created  by  the  SET  FIELDS  command.  CLEAR 
FIELDS  has  no  effect  unless  you  used  SET  FIELDS,  or  the  command  was 
activated  by  a  view  or  query  file.  Unlike  SET  FIELDS  TO,  which  removes 
only  the  active  database  fields  from  the  fields  list,  CLEAR  FIELDS  releases  all 
fields,  including  those  from  other  work  areas.  CLEAR  FIELDS  automatically 
performs  a  SET  FIELDS  OFF. 


GETS  releases  all  @...GETs  issued  since  the  last  CLEAR  ALL,  CLEAR  GETS, 
or  READ  command.  Unless  the  GETS  parameter  is  redefined  using  a 
Config.db  file,  dBASE  IV  permits  128  @...GETs  before  a  CLEAR  GETS  or 
READ  must  be  issued. 

The  maximum  number  of  GETs  allowed  is  1,023.  However,  the  number  you 
can  actually  use  is  limited  by  the  amount  of  memory  in  your  computer.  (See 
your  Getting  Starred  booklet  for  memory  limitations.)  For  most  purposes,  the 
default  value  of  128  is  sufficient. 
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CLEAR 


The  READ  command  releases  all  GETs,  unless  you  use  the  SAVE  option.  If 
you  use  the  SAVE  option,  you  must  CLEAR  GETs  before  the  maximum  num¬ 
ber  of  GETs  is  reached. 


CLEAR  GETS  does  not  release  memory  variables  or  array  elements. 


MEMORY  releases  all  memory  variables  (except  system  variables)  and  array 
elements.  CLEAR  MEMORY,  when  issued  at  the  dot  prompt,  performs  the 
same  function  as  the  RELEASE  ALL  command.  When  used  in  programs, 
however,  CLEAR  MEMORY  releases  all  PUBLIC  and  PRIVATE  memory  vari¬ 
ables  and  elements,  while  RELEASE  ALL  releases  only  PRIVATE  memory 
variables  and  elements  declared  in  the  program  currently  being  executed. 

MENUS  clears  all  bar  menus  from  the  screen  and  erases  them  from  memory. 
Use  this  command  to  clear  the  screen  of  all  menus,  and  to  make  the  memory 
used  by  menus  available  for  other  operations. 

POPUPS  clears  all  pop-up  menus  from  the  screen  and  erases  them  from 
memory.  Use  this  command  to  clear  the  screen  of  all  pop-up  menus,  and 
release  the  memory  used  by  pop-up  menus.  While  clearing  popups,  this  com¬ 
mand  also  DEACTIVATES  the  active  popup,  and  clears  all  ON  SELECTION 
commands  associated  with  the  pop-up  menus. 

TYPE  AHEAD  empties  the  type-ahead  buffer.  Use  CLEAR  TYPEAHEAD  when 
you  want  to  make  sure  that  there  are  no  keystrokes  in  the  type-ahead  buffer. 
This  is  particularly  useful  in  programs  when  you  want  the  user  to  enter 
information  before  the  program  continues.  For  instance,  place  it  before 
CHANGE,  READ,  WAIT,  or  similar  commands  to  ensure  that  dBASE  IV  acts 
upon  the  correct  characters. 


WINDOWS  removes  all  windows  from  the  screen  and  clears  them  from 
memory.  Any  window  definitions  that  you  have  not  saved  before  issuing  this 
command  are  lost.  If  you  save  your  window  definitions  to  a  disk  file,  you  can 
RESTORE  WINDOWS  from  a  disk  file  whenever  you  wish,  and  remove  them 
from  the  screen  and  memory  quickly  with  the  CLEAR  WINDOWS  command. 

When  you  issue  a  CLEAR  WINDOWS  command,  the  full  screen  is  restored. 
Any  text  that  was  covered  up  by  the  windows  becomes  visible. 

See  Also 

@...FILL,  @...TO,  CLOSE,  CREATE/ MODIFY  VIEW,  READ,  RELEASE, 
SET  FIELDS,  SET  FORMAT,  SET  TYPEAHEAD,  SET  VIEW 

Chapter  6,  "Customizing  dBASE  IV” 
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CLOSE 


CLOSE  is  used  to  close  alternate  files,  database  files,  format  files,  index 
(.ndx  and  .mdx)  files,  memo  files,  and  procedure  files. 

Syntax 

CLOSE  ALL/ ALTERNATE/ DATABASES/ FORMAT/INDEX/ PROCEDURE 

Usage 

CLOSE  ALL  closes  all  files  of  all  types  and  reselects  work  area  1. 

To  CLOSE  a  particular  file  type,  follow  the  command  with  one  of  the  key¬ 
words  given  above  under  “Syntax.” 

CLOSE  DATABASES  does  not  affect  work  area  10  if  a  catalog  is  open.  Besides 
closing  all  database  files,  it  closes  any  associated  index  (.ndx  and  .mdx)  files, 
memo  (.dbt)  files,  and  format  (.fmt)  files 

If  you  want  to  close  only  the  currently  selected  database  file  and  its  associ¬ 
ated  files,  issue  the  USE  command,  rather  than  the  CLOSE  command. 


Examples 

To  close  all  open  files  without  affecting  memory: 

.  CLOSE  ALL 

To  close  all  open  database,  index,  and  format  files: 
.  CLOSE  MTJBASES 
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COMPILE  reads  a  file  containing  dBASE  IV  source  code,  and  creates  an 
executable  object  code  file. 

Syntax 

COMPILE  <  filename  > 


Defaults 


Unless  the  file  is  on  the  default  drive  or  a  path  is  set,  the  filename  must 
include  the  drive  designator.  The  filename  must  also  include  a  path,  if 
the  file  is  not  on  the  default  directory  or  on  a  path  set  with  the  SET  PATH 
com  mand. 


COMPILE  can  only  compile  a  source  file.  This  command  looks  for  a  file  with 
a  prg  extension,  unless  you  provide  another  extension  in  the  command  line. 
Source  files  contain  dBASE  IV  commands  and  functions,  and  typically  have 
a  Prg  (program),  .prs  (SQL  program),  .fmt  (format),  .frg  (generated  report 
form),  .lbg  (generated  label),  .qbe  (query),  or  .upd  (update  query)  extension. 

Although  the  source  file  may  have  any  extension,  COMPILE  will  always  write 
the  object  file  with  a  .dbo  extension. 

Usage 


Object  files  contain  an  execute-only  form  of  dBASE  code.  Earlier  versions  of 
dBASE  did  not  generate  object  code  files.  COMPILEd  files,  therefore,  cannot 
be  used  by  dBASE  III  PLUS  or  dBASE  III.  These  object  files  allow  dBASE  IV 
to  execute  much  faster  than  earlier  versions. 

When  you  DO  a  program  file,  the  source  code  is  compiled  into  an  object 
code  file,  and  then  the  object  code  is  executed.  COMPILE  allows  you  to  gen¬ 
erate  the  object  code  file  without  executing  the  code. 

You  cannot  modify  an  object  file.  You  can  modify  the  source  code  file,  but 
should  verify  that  changes  to  the  source  code  file  are  COMPILEd  to  the 
object  code  file. 


If  SET  DEVELOPMENT  is  ON,  DO  compares  the  time  and  date  stamp 
of  a  .prg  file  with  the  time  and  date  stamp  of  its  associated  .dbo  file.  If  the 
.dbo  file  is  older  than  the  .prg  file,  DO  recompiles  the  .prg  file  before 
executing  it. 
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The  dBASE  IV  program  editor,  which  can  be  accessed  from  MODIFY 
COMMAND  or  the  Control  Center,  will  delete  an  old  dbo  file  when  a  .prg 
file  is  modified,  and  then  recompile  the  new  .prg  file  (generating  a  new  .dbo 
file)  when  you  save  it.  As  other  text  editors  will  not  delete  the  old  .dbo  file 
and  recompile  a  new  one,  SET  DEVELOPMENT  allows  you  to  verify  that  DO 
does  not  execute  an  outdated  .dbo  file. 

If  you  do  not  use  the  MODIFY  COMMAND  program  editor,  and  do  not  SET 
DEVELOPMENT  ON,  you  must  recompile  your  source  code  files  after  modi¬ 
fying  them,  or  else  the  changes  will  not  be  written  to  the  object  file. 

COMPILE  checks  each  line  of  the  source  code  file  for  syntactical  accuracy 
and  proper  control  structure,  and  flags  syntax  errors  and  control  structure 
violations  (such  as  missing  ENDDOs  and  ENDIFs).  If  a  macro  appears  in  a 
command  line,  however,  it  is  expanded  and  parsed  at  execution  time. 

As  COMPILE  always  writes  the  object  file  with  a  .dbo  extension,  you  should 
give  source  code  files  unique  names  so  that  one  file  does  not  overwrite  a  file 
COMPILEd  earlier  with  the  same  name. 

dBASE  IV  supports  the  concept  of  procedures  within  any  program  file  by 
maintaining  a  procedure  list  at  the  beginning  of  every  object  (.dbo)  file.  If  a 
source  file  starts  with  a  command  other  than  PROCEDURE  or  FUNCTION, 
the  code  is  compiled  as  a  procedure  and  added  to  the  procedure  list  in  the 
object  file  with  the  same  name  as  the  source  file.  Atypical  .prg  file  such  as: 

*  Main.prg 
?  "MAIN' 

RETURN 

is  compiled  into  a  .dbo  file  containing  one  procedure,  Main.  When  you  enter 
DO  MAIN,  this  name  is  used  to  locate  the  .dbo  file,  and  then  used  to  locate 
the  procedure  within  the  .doo  file. 

A  source  file  can  include  more  than  one  procedure,  such  as: 

*  Main.prg 
?  "MAIN' 

DO  S dob 
RETURN 


PROCEDURE  Site 
?  "  SUES’ 

RETURN 

Note  that  only  code  found  at  the  beginning  of  a  file  is  given  the  default  pro¬ 
cedure  name.  Loose  code  between  RETURN  and  PROCEDURE  causes  a 
compile-time  error. 
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COMPILE 


Any  procedure  found  in  an  active  .dbo  file  is  available  to  the  DO  command. 
If  A.dbo  calls  B.dbo  calls  C.dbo,  all  the  procedures  defined  within  A,  B,  and 
C  are  available  to  any  procedure  in  C.  dBASE  IV  still  supports  SET 
PROCEDURE  from  dBASE  III  and  dBASE  III  PLUS,  although  this  command 
is  only  required  to  gain  access  to  procedures  in  a  file  not  activated  by  DO 
<  filename  >  . 


Tips 

COMPILE  places  all  command  keywords  in  a  pre-designated  order  before 
generating  object  code.  This  order  is  usually  the  same  as  given  in  the  para¬ 
digms  under  the  “Syntax”  heading  for  each  command  and  function.  Compile 
time  can  be  improved  for  long  commands  by  entering  commands  in  the 
order  given  in  the  syntax  paradigms. 

dBASE  IV  optimizes  expressions  during  compilation.  If  you  use  constants  in 
the  source  code,  the  compiler  computes  and  saves  the  value  in  the  object 
code  file.  For  example, 

x  -  1+3+4 
is  optimized  and  saved  as 


Comparing  two  string  constants  in  an  expression  could  cause  a  problem.  For 
example, 


evaluates  to  true  (.T.)  if  SET  EXACT  is  OFF,  but  to  false  (.F.)  if  SET  EXACT  is 
ON.  If  you  SET  EXACT  ON  during  execution  of  the  code,  the  expression  will 
still  be  false  because  it  was  optimized  and  saved  as  a  logical  false  (.F.)  during 
compilation. 

See  Also 

DEBUG  DO,  FUNCTION,  MODIFY  COMMAND,  PROCEDURE,  SET  DEBUG, 
SET  DEVELOPMENT,  SET  EXACT,  SET  PATH,  SET  PROCEDURE,  SET  TRAP 
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CONTINUE 


CONTINUE  searches  for  the  next  record  in  the  active  database  file  that 
meets  the  condition  specified  by  the  most  recent  LOCATE  command. 


Syntax 

CONTINUE 


Usage 

A  CONTINUE  search  ends  when  it  finds  a  record  that  meets  the  specified 
LOCATE  condition,  or  when  it  reaches  the  end  of  the  LOCATE  scope  or  the 
end  of  the  file. 

LOCATE  and  CONTINUE  are  specific  to  the  work  area  in  which  you  issue 
them.  You  can  issue  different  LOCATE  and  CONTINUE  commands  in  each 
work  area.  If  you  leave  a  work  area,  the  LOCATE  condition  will  still  be  in 
effect  when  you  return. 


Record  Pointer 

If  SET  TALK  is  ON,  and  if  CONTINUE  finds  another  record  meeting  the  con¬ 
dition,  the  record  number  is  displayed.  Otherwise,  the  message  End  of 
LOCATE  scope  appears,  FOUNDQ  returns  a  logical  false  (.F.),  and  the 
record  pointer  is  positioned  at  the  last  record  of  the  LOCATE  scope  or  at  the 
end  of  the  file.  If  the  record  pointer  is  at  the  end  of  the  file,  EOF()  returns  a 
logical  true  (.T.). 

Example 

To  locate  records  containing  "OAK'  in  the  Descript  field  of  the  Stock  data 
base  file: 

.  USEStodc 

.  LOCATE  FOR  *OfiK\  S  Descript 
Record  =  SJ 
.  ?  Descript  J 
UCOD,  OK,  2-TOOT,  SGL1ARE 
.  CENTIME  ! 

Record  =  15 

.  ?  Descript 
UCCO,  OK,  FANCY 
.  CENTIME 
Bid  of  LOCATE  sccpe. 


The  message  End  of  LOCATE  scope  indicates  that  no  more  records  match 
the  FOR  or  WHILE  condition,  or  that  the  scope  has  been  exhausted. 
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CONTINUE 


See  Also 

EOF(),  FIND,  FOUND(),  LOCATE,  SEEK,  SEEK() 
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CONVERT 


CONVERT  adds  a  field  to  a  database  file’s  structure  which  holds  information 
required  for  multi-user  lock  detection. 


Syntax 

CONVERT  [TO  <  expN>  ] 


Usage 

This  command  adds  a  character  field  called  _dbaselock  to  the  structure  of 
the  currently  selected  database  file.  The  length  of  the  field  is  determined  by 
the  numeric  expression,  which  may  be  a  number  from  8  to  24.  The  default 
is  16. 

The  _dbaselock  field  reserves  an  area  for  the  following  values: 


Count 


Time 


Date 


Name 


A  two-byte  hexadecimal  number  used  by  the  CHANGEQ 
function. 

A  three-byte  hexadecimal  number  that  records  the  time  a  lock 
was  placed. 

A  three-byte  hexadecimal  number  that  records  the  date  a  lock 
was  placed. 

A  zero-  to  16-character  representation  of  the  log-in  name  of  the 
computer  that  placed  a  lock,  if  a  lock  is  active. 


The  count,  time,  and  date  portions  of  the  field  always  take  the  first  eight 
characters. 

If  you  CONVERT  the  _dbaselock  field  to  the  default  of  16  characters,  the 
log-in  name  will  be  eight  characters  long.  If  you  CONVERT  the  field  to  the 
maximum  of  24  characters,  the  log-in  name  will  be  16  characters  long.  If 
you  CONVERT  the  field  to  eight  characters,  no  space  is  reserved  for  the  log¬ 
in  name,  and  the  name  is  not  written  in  the  record. 

Every  time  a  record  is  updated,  the  count  portion  of  _dbaselock  is  rewritten. 
If  you  use  the  CHANGEQ  function,  the  count  portion  of  the  field  is  read 
from  the  disk  again  and  compared  to  the  previous  value,  which  was  stored  in 
memory  when  the  record  was  initially  read.  If  the  values  are  different, 
another  user  has  changed  the  record,  and  the  CHANGEQ  function  returns  a 
logical  true  (.T.). 

You  can  reset  the  value  to  false  by  repositioning  the  record  pointer.  GOTO 
RECNOQ  rereads  the  current  record’s  _dbaselock  field,  and  a  subsequent 
CHANGEQ  command  should  return  a  false  (  F.)  unless  another  user  has 
made  another  change  in  the  interims 
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The  LKSYS()  function  returns  the  log-in  name,  date,  and  time  portions  of 
the  _dbaselock  field.  It  indicates  who  has  locked  the  record  or  file,  and 
when  the  lock  was  placed.  If  you  place  a  file  lock,  the  _dbaselock  field  of  the 
first  record  in  the  database  file  contains  the  information  used  by  CHANGE() 
and  LKSYS(). 

Tip 

CONVERT  copies  the  .dbf  file  to  new  file  with  a  .cvt  extension,  then  creates 
a  new  .dbf  file  containing  the  _dbaselock  field.  The  .cvt  file  contains  the 
original  file  structure  before  CONVERT. 


See  Also 

CHANGEQ,  FLOCKQ,  LKSYS(),  LOCKQ,  NETWORK(),  SET  LOCK, 
SET  REPROCESS,  UNLOCK 
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COPY 


COPY  duplicates  all  or  part  of  an  active  database  file,  creating  a  new  file. 
COPY  is  also  the  primary  command  used  to  export  data  to  non-dBASE 
programs. 

Syntax 

COPY  TO  <  filename  > 

[[TYPE]  <  file  typo  ]  [FIELDS  <  field  list >  ] 

[<  scope  >  ]  [FOR  <  condition  >  ]  [WHILE  <  condition  >  ] 


Defaults 

This  command  copies  all  records,  including  records  marked  for  deletion, 
unless  SET  DELETED  is  ON,  or  unless  you  specify  a  scope,  FOR,  or  WHILE 
clause  to  limit  the  records  copied.  All  fields  are  copied,  unless  you  specify  a 
FIELDS  list  or  use  the  SET  FIELDS  command.  Memo  fields  are  copied  only 
if  the  new  file  is  another  dBASE  IV  database  file. 

A  directory  listing  of  new  files  created  by  the  COPY  command  shows  the 
dates  on  which  the  new  files  were  copied. 

If  you  do  not  enter  a  file  type  with  the  command,  the  file  is  copied  to 
another  dBASE  IV  database  (.dbf)  file. 

Usage 

If  the  TO  file  is  another  dBASE  IV  database  (  dbf)  file,  do  not  specify  [TYPE] 
or  [<  file  typo  ].  This  command  automatically  copies  memo  (.dbt)  files 
when  the  TO  file  is  a  dBASF  IV  database  file.  If  the  TO  file  is  an  ASCII  text 
file  or  a  file  supported  by  another  software  program,  specify  one  of  the  file 
type  options. 


NOTE 

The  COPY  command  does  not  verify  that  the  files  you  build  are  com¬ 
patible  with  another  software  program.  You  may  specify  field  lengths, 
record  lengths,  number  of  fields,  or  number  of  records  that  are  incom¬ 
patible  with  other  software.  Note  the  file  limitations  of  your  other  soft¬ 
ware  program  before  exporting  database  files  with  COPY. 
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COPY 


Options 

The  options  for  exported  file  types  are: 

■  DELIMITED  [WITH  <  delimiter>  ]  —  ASCII  text  (.txt)  file  with  comma 
field  separators  and  character  fields  enclosed  within  delimiter  charac¬ 
ters.  All  fields  are  separated  by  commas.  Character  fields  are  delimited 
with  double  quotes  by  default,  unless  you  specify  another  delimiter  char¬ 
acter  using  the  WITH  <  delimiter>  option.  Records  in  the  text  file  are 
variable  length,  and  every  record  ends  with  a  carriage  return  and  line 
feed. 

■  DELIMITED  [WITH  BLANK]  —  ASCII  text  (.txt)  file  with  a  single  space 
character  separating  each  field,  but  with  no  delimiters  enclosing  charac¬ 
ter  fields.  Records  in  the  text  file  are  variable  length,  and  every  record 
ends  with  a  carriage  return  and  line  feed. 

■  SDF  —  System  Data  Format  ASCII  (.txt)  file.  Character  data  is  not  delim¬ 
ited,  and  fields  are  not  separated  with  a  character.  Records  are  fixed 
length,  the  same  length  as  the  record  in  the  database  file,  and  every 
record  ends  with  a  carriage  return  and  line  feed. 

■  dBASEII  —  dBASE  II  database  (.db2)  file.  The  dBASE  II  file  is  given  a 
.db2  file  extension,  rather  than  a  .dbf  extension,  to  distinguish  it  from  the 
original  dBASE  IV  file.  You  should  rename  the  file  to  include  a  .dbf 
extension  before  you  use  it  in  dBASE  II. 

■  RPD  —  RapidFile  data  (.rpd)  file. 

■  FW2  —  Framework  II  (.fw2)  database. 

■  SYLK  —  MultiPlan  spreadsheet  formula.  Database  records  are  converted 
to  MultiPlan  rows,  and  database  fields  are  converted  to  columns.  No  file 
extension  is  written  with  the  output  file. 

■  DIF  —  VisiCalc  version  1  (.dif)  file  format.  Database  records  are  con¬ 
verted  to  VisiCalc  rows,  and  database  fields  are  converted  to  columns. 

■  WKS  —  Lotus  1-2-3  spreadsheet  (.wks)  format,  release  1A  Database 
records  are  converted  to  Lotus  1-2-3  rows,  and  database  fields  are  con¬ 
verted  to  columns. 

When  COPY  is  used  to  write  any  of  the  three  supported  spreadsheet  formats 

(SYLK,  DIF,  WKS),  the  field  names  are  written  as  column  headers  in  the 

resulting  file.  The  file  is  created  in  row  major  order. 
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COPY 


Special  Cases 

Use  the  EXPORT  command,  rather  than  the  COPY  command,  to  convert  files 
to  PFS:FILE.  EXPORT  and  COPY  both  convert  files  to  Framework  II, 
dBASE  II,  and  RapidFile  file  formats.  COPY,  however,  cannot  create  a 
PFS:FILE  form. 


Tips 

Do  not  use  the  single  letters  A  through  J,  or  the  letter  M,  as  a  database  file¬ 
name  if  you  COPY  TO  a  dBASE  IV  database  file.  These  letters  are  reserved  as 
default  alias  names.  You  can,  however,  specify  AA(for  example)  as  a  data¬ 
base  filename. 

If  a  relation  is  active  and  you  have  specified  fields  from  another  work  area 
with  the  SET  FIELDS  command  or  with  the  FIELDS  clause,  the  resultant  file 
contains  the  data  from  related  records  in  other  work  areas. 


Example 


To  copy  all  the  records  in  the  Transact  database  file  whose  Client. id  is 
C00002  to  a  database  file  called  Temp: 


.  USE  Transact 

.  COPY  TO  Terrp  FOR  Client-id*  'CCKE' 

2  records  ccpied 
c  USE  Tenp.cbf 
.  LIST 

Record#  CUBfUD  ORDERJD  ttTEJIUNS  IM0ICED  TOTALUILL 

1  (TTH?  87-107  C2/12/87")  J.  J  1250.00 

2  am?  87-110  Q3/C9/8LJ  -I:  175.00 


See  Also 

APPEND  FROM,  COPY  FILE,  COPY  STRUCTURE,  EXPORT,  IMPORT, 
SET  DELETED,  SET  FIELDS,  SET  SAFETY 
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COPY  FILE  creates  a  duplicate  of  any  file. 


Syntax 

COPY  FILE  <  filename  >  TO  <  filename  > 

Usage 

You  must  specify  the  filenames  and  file  extensions  for  both  files.  If  you  want 
to  copy  a  file  to  another  drive  or  directory,  you  must  also  provide  the  drive 
designator  and  directory  name.  You  do  not  need  to  include  the  directory  or 
drive  designator  of  the  first  file,  if  it  is  already  established  with  the  SET  PATH 
command  or  the  PATH  setting  in  the  Config.db  file. 

You  cannot  use  COPY  FILE  to  copy  an  open  file. 


Tips 

If  you  copy  a  database  file  that  has  memo  fields,  you  must  copy  the  associ¬ 
ated  memo  (  dbt)  file  separately.  You  may  use  the  COPY  command  to  copy 
records  from  an  open  database  file. 

Do  not  use  the  single  letters  A  through  J,  or  the  letter  M,  as  database 
filenames  because  they  are  reserved  as  default  alias  names.  You  can,  how¬ 
ever,  specify  AA(for  example)  as  a  database  filename. 


Example 

To  make  a  duplicate  of  a  dBASE  program  file: 

.  CCFY  FILE  Accts.prg  70  Oldaccts.prg 
2123  bytes  oopied 

See  Also 

COPY 
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COPY  INDEXES 


COPY  INDEXES  converts  index  (.ndx)  files  into  multiple  index  (.mdx)  file 
tags. 


Syntax 

COPY  INDEXES  <  .ndx  file  list >  [TO  <  .mdx  filename  >  ] 


Usage 

If  you  do  not  specify  an  .mdx  file  with  the  TO  clause,  the  tag  is  written  to  the 
production  .mdx  file.  If  a  production  .mdx  file  does  not  exist,  it  is  created 
with  the  same  name  as  the  active  database  file,  and  the  database  file  header 
is  updated  to  indicate  the  presence  of  a  production  mdx  file. 

If  you  use  a  TO  clause,  the  tag  is  written  to  the  specified  mdx  file.  If  the 
.mdx  file  you  supply  in  the  TO  clause  does  not  exist,  a  new  .mdx  file  is  cre¬ 
ated  and  given  the  filename  specified  in  the  TO  clause. 

You  may  copy  a  maximum  of  47  index  (.ndx)  files  to  .mdx  tags  with  one 
COPY  INDEXES  command,  because  each  .mdx  file  may  contain  47  tags. 


Special  Cases 

In  a  network  environment,  the  database  file  must  be  in  exclusive  use  before 
you  attempt  to  copy  an  .ndx  file  to  an  .mdx  tag. 


Example 

To  convert  the  Cus.name  inoex  file  of  the  Client  database  file  to  a  tag  in  the 
production  mdx  file: 


.  USE  CL  ierrt  INDEX  CLajvm 

.  COPf  IfDEX  QjsjTBme 

IdK  indexed  8  records  indexed 

.  DISPLAY  STATUS 

dr  rent  Ly  Selected  Database: 

Select  area:  1,  Database  in  Use:  C:\SET\CUBfT.CBF  Alias:  CLIENT 
Production  W)X  file:  C:\SET\a_IBfT.MK 


Index  TAG: 
Index  TAG: 
Master  Index  TAG: 
Meno  file: 


CUBIT  Key:  CUBIT 
CUENUD  Key:  CUBIT_ID 
CUS_NAf€  Key:  Lastname+firstrame 
C:\SET\Q_IENT.D8T 
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COPY  INDEXES 


See  Also 

COPY  TAG,  INDEX,  KEY(),  MDX(),  NDX(),  SET  INDEX,  SET  ORDER, 
TAG(),  USE 
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COPY  MEMO 


COPY  MEMO  copies  the  information  from  a  single  memo  field  to  another 
file. 

Syntax 

COPY  MEMO  <  memo  field  name>  TO  <  filename  >  [ADDITIVE] 


Default 

If  you  do  not  provide  an  extension  for  the  TO  file,  a  .txt  extension  is  written. 

Usage 

This  command  exports  the  information  from  a  memo  field  in  the  current 
record  to  a  file  on  disk. 

If  you  want  to  copy  a  file  to  another  drive  or  directory,  you  must  provide  the 
drive  designator  and  directory  name. 

You  can  precede  the  field  name  with  an  alias,  and  copy  memo  fields  from 
other  work  areas.  If  the  field  is  contained  in  a  SET  FIELDS  list,  you  do  not 
have  to  use  the  alias. 


Options 

ADDITIVE  causes  the  contents  of  the  memo  field  to  be  appended  to  the  end 
of  the  named  file.  If  you  do  not  use  the  ADDITIVE  option  and  the  filename 
already  exists  on  disk,  the  contents  of  the  memo  field  overwrite  any  existing 
information  in  the  file. 

This  comm  and  writes  to  a  file  without  warning,  if  SET  SAFETY  is  OFF.  If 
SET  SAFETY  is  ON,  you  are  prompted  with  a  warning  message  before  the 
file  is  written. 
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COPY  MEMO 


Example 

To  write  the  information  contained  in  the  field  Clien_hist  to  a  file  named 
Cus_text,  appending  the  information  in  the  current  record  to  information 
that  already  exists  in  the  file: 

.  OOPf  t&C  CL  ienJiist  TO  CkiLJext  ADDITIVE 

See  Also 

APPEND  MEMO,  COPY,  COPY  FILE 
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COPY  STRUCTURE 


COPY  STRUCTURE  copies  the  structure  of  the  active  database  file  to  a  new 
file,  but  does  not  copy  any  records. 


Syntax 

COPY  STRUCTURE  TO  <  filename:.  [FIELDS  <  field  list>  ] 


Defaults 

The  filename  must  include  the  drive  designator  and  directory,  if  you  want 
the  resultant  file  written  to  a  drive  or  directory  other  than  the  default.  Unless 
otherwise  specified,  the  TO  file  is  assigned  a  .dbf  extension. 


Usage 

This  command  copies  the  entire  database  file  structure  unless  limited  by  the 
FIELDS  option.  The  result  is  another  database  file  with  either  an  identical 
structure  to  the  first  file,  or,  if  you  specify  the  FIELDS  option,  with  a  subset 
of  the  fields  in  the  first  file.  No  records  are  copied. 

If  SET  SAFETY  is  OFF,  a  new  database  file  will  overwrite  an  existing  file 
without  warning. 


Programming  Notes 

You  may  COPY  STRUCTURE  under  program  control  to  create  temporary  or 
transaction  database  files.  You  may  then  add  records  to  the  transaction  file 
with  the  APPEND  command,  or  add  blank  records  with  APPEND  BLANK 
and  place  data  in  the  records  with  REPLACE. 


Example 

To  copy  the  structure  of  the  Client  database  file  to  a  file  called  Temp: 


.  USE  Client 
.  ary  STUCTUFE  TO  Terrp 


See  Also 

APPEND,  APPEND  BLANK,  APPEND  FROM,  DISPLAY  STRUCTURE, 
REPLACE,  SET  SAFETY 
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COPY  STRUCTURE 
EXTENDED 


COPY  STRUCTURE  EXTENDED  creates  a  new  database  file  whose  records 
contain  the  structure  of  the  current  file. 


Syntax 

COPY  TO  <  filename  >  STRUCTURE  EXTENDED 

Usage 

This  command  creates  a  database  file  with  five  fields:  FIELD_NAME, 
HELD. TYPE,  FIELD. LEN,  FIELD. DEC,  and  FIELD. IDX.  Records  in  the 
new  file  contain  the  field  name,  data  type,  field  width,  number  of  decimal 
places  (in  a  numeric  field),  and  index  flag  for  each  field  in  the  active  data¬ 
base  file. 

This  command  is  most  often  used  within  application  programs  in  conjunc¬ 
tion  with  the  CREATE  FROM  command.  CREATE  FROM  creates  a  database 
file  from  the  extended  structure  file.  You  can  thereby  create  a  database  file 
in  a  program  without  using  the  interactive  CREATE  or  MODIFY 
STRUCTURE  commands. 


Example 

See  the  CREATE  FROM  command. 


See  Also 

APPEND  FROM,  CREATE  FROM,  LIST/ DISPLAY  STRUCTURE 
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COPY  TAG 


COPY  TAG  converts  multiple  index  (.mdx)  file  tags  into  index  (.ndx)  files. 


Syntax 

COPY  TAG  <  tag  name>  [OF  mdx  filename]  TO  <  .ndx  filename  > 


Default 

Using  the  OF  clause,  you  may  specify  the  .mdx  file  that  contains  the  tag. 


Usage 

If  you  do  not  use  the  TO  clause,  this  command  creates  an  .ndx  file  that  has 
the  same  name  as  the  .mdx  tag.  The  database  file  must  be  in  use,  because 
COPY  TAG  recreates  the  .ndx  file  from  the  expression  contained  in  the  .mdx 
file  tag. 


Special  Cases 

In  a  network  environment,  the  database  file  must  be  in  exclusive  use  before 
you  attempt  to  copy  .mdx  tags  to  .ndx  files. 


Example 

To  copy  the  OrderJd  tag  from  the  Stock  .mdx  file  to  an  .ndx  Hie  called 
Items_  id: 


.  USE  Stock 

.  COPY  TAG  OrderJd  TO  ItmsJdjtit 
10CK  indexed  17  records  indexed 

.  DISPLAY  STATUS 
Cirraritly  Selected  Database: 

Select  area:  1,  Database  in  Use:  C:\SET\ST0CX.D8F  Alias:  STOCK 
tester  Index  file:  C:\SETMTEMSJD.N>X  Key:  ORDERJD 
Production  N>X  file:  C:\SEASTOOC.MK 

Index  TAG:  ORDERJD  Key:  ORDERJD 

Index  TAG:  PARTJWE  Key:  PARTJWE 


See  Also 

COPY  INDEX,  INDEX,  MDX(),  NDXQ,  SET  INDEX,  SET  ORDER,  TAG() 
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COPY  TO  ARRAY 


COPY  TO  ARRAY  fills  an  existing  array  with  the  contents  of  one  or  more 
records  from  the  active  database  file. 


Syntax 

COPY  TO  ARRAY  <  array  name>  [FIELDS  <  fields  list  >  ] 

[<  scope  >  ]  [FOR  <  condition  >  ]  [WHILE  <  condition  >  ] 

Usage 

This  command  copies  selected  records  and  fields  from  a  database  file  into  an 
existing  array. 

For  each  record  in  the  database  file,  the  first  field  is  stored  in  the  first  col¬ 
umn,  the  second  field  in  the  second  column,  and  so  on.  This  process  contin¬ 
ues  until  there  are  either  no  more  fields  or  no  more  array  columns.  If  the 
database  file  has  more  fields  than  the  array  can  hold,  the  excess  fields  are 
not  stored.  If  the  database  file  has  fewer  fields  than  the  array,  the  excess 
array  elements  remain  unchanged.  Each  record  becomes  a  row  in  the  array, 
although  memo  fields  cannot  be  copied  to  an  array. 

If  you  declare  a  single-dimensioned  array,  such  as 
.  DECLARE  Transacted 

COPY  TO  ARRAY  will  only  be  able  to  copy  one  record  containing  five  fields 
to  the  array. 

Unless  you  specify  a  scope,  the  process  begins  with  the  first  record  in  the 
database  file  and  continues  until  there  are  either  no  more  records  in  the 
database  file  or  there  no  more  rows  in  the  array. 

The  data  types  of  the  array  elements  are  the  same  as  the  corresponding  field 
types  in  the  database  file. 


Options 

This  command  attempts  to  copy  all  fields  (except  memo  fields),  unless  you 
use  the  FIELDS  option  or  the  SET  FIELDS  command. 

If  you  use  the  FOR  clause,  the  condition  is  evaluated  before  each  record  in 
the  database  file  is  copied  to  the  array.  A  record  is  copied  to  the  array  only  if 
the  condition  evaluates  to  a  logical  true  (.T.).  If  you  use  the  WHILE  clause, 
no  further  information  is  copied  once  the  condition  evaluates  to  a  logical 
false  (.F.). 
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Example 

To  COPY  the  records  in  the  Transact  database  file  that  have  L0001  for  the 
Client.id,  first  determine  how  many  elements  the  array  will  require,  define 
an  array  called  Records,  and  then  execute  the  COPY  TO  ARRAY  command: 


.  USE  Transact  SS  Transact. cbf  has  fi\ m  fields. 

.  CCLMT  FOR  Cl  ient_id  =  "ICTTM"  TO  ncrt 
2  records 

.  DECLARE  RcccrdsDrcntsSJ  SS  Define  the  array. 

.  CCPf  TO  ARRAY  Records  FOR  Cl  ientjd  =  ’UHDV 
2  records  copied 


See  Also 

APPEND  FROM,  COPY  FILE,  COPY  STRUCTURE,  EXPORT,  SET  DELETED, 
SET  FIELDS,  SET  SAFETY 
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COUNT 


COUNT  tallies  the  number  of  records  in  the  active  database  file  that  m  atch 
specified  conditions. 


Syntax 

COUNT  [TO  <  memvar>  ]  [<  scope  >  ]  [FOR  <  condition  >  ] 
[WHILE  <  condition  >  ] 


Usage 

If  SET  TALK  is  ON,  this  command  counts  the  number  of  records  and  dis¬ 
plays  the  tally.  If  you  specify  a  condition  with  a  FOR  or  WHILE  clause,  or 
limit  the  number  of  records  with  a  scope,  the  tally  indicates  the  number  of 
records  that  meet  the  condition  or  fall  within  the  scope. 

If  you  include  the  TO  clause,  COUNT  creates  a  memory  variable  and  stores 
the  tally,  as  a  type  N  (Binary  Coded  Decimal)  number,  to  this  memory 
variable. 


Special  Cases 

In  a  network  environment,  COUNT  automatically  locks  the  file  during  its 
operation  if  SET  LOCK  is  ON  (the  default),  and  unlocks  it  after  the  count  is 
complete.  If  SET  LOCK  is  OFF,  a  COUNT  can  still  be  performed,  but  the 
result  may  not  be  reliable  if  another  user  is  changing  the  database  file. 


Example 

To  determine  the  number  of  March  orders  in  the  Transact  database  file: 
.  L55F  Transact 

«  COM  FOR  LIKE CCB/77/&* J)  TOC  (Da  tc_trans))  TO  tordunt 
6  records 

.  ?  * There  uere  ’  H.WIM(STR(torch_£nt^2/0))-t/'  orders  in  torch.* 

There  were  6  orders  in  torch. 


See  Also 

AVERAGE,  CALCULATE,  RECCOUNTQ,  SUM 
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CREATE  or  MODIFY 
STRUCTURE 


CREATE  or  MODIFY  STRUCTURE  gives  you  access  to  the  database  file 
design  screen. 

CREATE  allows  you  to  build  a  structure  for  a  new  database  file.  MODIFY 
STRUCTURE  allows  you  to  modify  the  structure  of  a  previously  created  data¬ 
base  file.  Both  commands  provide  the  same  screen  for  designing  the  file 
structure. 

The  structure  of  a  database  file  is  the  definition  of  field  names,  field  types, 
field  lengths,  number  of  decimal  places  (for  numeric  fields),  and  a  flag  indi¬ 
cating  the  presence  of  an  .mdx  tag  for  each  field. 

Syntax 

CREATE  <  filenames  /MODIFY  STRUCTURE 


Defaults 

Unless  you  explicitly  provide  a  drive  and  directory  with  the  filename, 
CREATE  writes  the  new  database  file  in  the  default  drive  and  directory  loca¬ 
tion.  Unless  you  specify  a  different  extension,  the  database  file  is  given  a  dbf 
extension. 

You  do  not  specify  a  filename  with  MODIFY  STRUCTURE.  This  command 
can  only  modify  the  structure  of  the  active  database  file. 

If  a  catalog  is  active  when  you  create  a  database  file,  the  file  will  be  added  to 
the  catalog. 


Usage 

CREATE  <  new  file  >  and  MODIFY  STRUCTURE  provide  the  same  design 
screen  for  creating  or  changing  the  database  file  structure.  The  structure 
contains  definitions  for  each  field  in  the  database  file. 

You  define  the  structure  of  a  new  database  file  by  providing  the  following 
information  for  each  field: 

Field  Name 

Type 

Width 

Decimal  Places  (for  a  numeric  field) 

Field  Index  Flag  (if  true,  a  tag  is  added  to  the  production  .mdx  file, 
indexed  on  this  field) 
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The  field  name  may  be  up  to  10  characters  long,  and  may  consist  of  letters, 
numbers,  and  the  underscore  character.  The  field  name  cannot  contain 
embedded  blank  characters  and  the  first  character  of  the  field  name  must  be 
a  letter.  When  you  have  finished  entering  the  field  name,  press  — 

You  determine  the  field  type  by  entering  the  first  letter  of  the  data  type 
(Character,  Numeric  (Binary  Coded  Decimal^,  Floating  point  numeric,  Logi¬ 
cal,  Date,  or  Memo),  or  by  pressing  the  Spacebar  until  the  desired  data  type 
appears  and  then  selecting  it  by  pressing  •<-*. 

You  must  specify  a  field  width  for  numeric  and  character  fields.  This  is  the 
maximum  number  of  digits  or  characters  you  intend  to  enter  in  the  field. 
Character  fields  may  be  up  to  254  characters  long;  numeric  fields  may  be  up 
to  20  digits,  including  the  sign  and  a  decimal  point. 

Logical,  Date,  and  Memo  fields  all  have  predefined  widths,  and  date  fields 
are  always  8  bytes.  Memo  fields  are  automatically  assigned  a  length  of  10 
bytes  in  the  database  file,  although  each  memo  field  entry  may  contain  up  to 
512K.  Data  you  enter  in  memo  fields  is  not  stored  in  the  database  (.dbf)  file, 
but  in  an  associated  memo  (.dbt)  text  file.  The  10  bytes  identify  the  location 
of  memo  field  entries  in  the  memo  file. 

If  you  specify  Y  in  the  Index  column  of  the  design  screen,  dBASE  IV  will 
create  an  index  tag  on  that  field  in  the  production  .mdx  file. 

You  can  define  a  record  having  up  to  255  fields.  The  maximum  size  of  a 
record  is  4,000  bytes,  not  including  memo  field  entries.  Each  character  posi¬ 
tion  in  a  field  takes  up  one  byte. 

Instructions  and  error  messages  appear  at  the  bottom  of  the  screen.  The 
pull-down  menus  at  the  top  of  the  screen  allow  you  to  work  directly  with  the 
database  file  structure  and  records.  You  may  print  the  database  file  structure, 
create  indexes,  sort  the  file,  remove  indexes,  and  append  records  to  the  file. 


Tips 

MODIFY  STRUCTURE  makes  a  backup  copy  of  the  database  file  with  a  bak 
extension,  and  a  backup  of  the  .dbt  file  with  a  .tbk  extension.  After  the  struc¬ 
ture  modifications  are  completed,  this  command  appends  the  contents  from 
the  backup  files  into  the  modified  database  file.  Since  MODIFY  STRUCTURE 
will  not  be  able  to  create  backup  files  if  the  disk  or  current  directory  is  full, 
you  should  make  sure  that  you  have  enough  space  available  for  the  backup 
files  before  you  modify  a  file’s  structure. 

Because  MODIFY  STRUCTURE  appends  data  into  the  new  file,  you  may  lose 
your  data  if  you  interrupt  your  computer  while  the  command  is  saving 
changes. 
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Special  Cases 

In  a  network  environment,  the  database  Hie  must  be  in  exclusive  use  before 
you  can  modify  its  structure. 

You  should  not  change  a  Held’s  name  and  its  width  or  type  at  the  same  time. 

If  you  do,  dBASE  IV  will  not  be  able  to  append  data  from  the  old  field,  and 
your  new  field  will  be  blank.  Change  the  name  of  a  field,  save  the  file,  then 
use  MODIFY  STRUCTURE  again  to  change  the  field’s  width  or  data  type. 

You  also  should  not  insert  or  delete  fields  from  a  database  file  and  change 
field  names  at  the  same  time.  If  you  change  field  names,  MODIFY  STRUC¬ 
TURE  appends  data  from  the  old  file  by  using  the  field  position  in  the  file.  If 
you  insert  or  delete  fields  as  well  as  changing  field  names,  therefore,  you  are 
changing  field  positions  and  could  lose  data.  You  can,  however,  change  field 
widths  or  data  types  the  same  time  as  you  insert  or  delete  fields.  In  those 
cases,  since  MODIFY  STRUCTURE  appends  data  by  field  name,  the  data  will 
be  appended  correctly. 

dBASE  IV  will  successfully  convert  data  for  a  number  of  field  type  conver¬ 
sions.  If  you  change  field  types,  however,  keep  a  backup  copy  of  your  origi¬ 
nal  file,  and  check  your  new  files  to  make  sure  the  data  has  converted 
correctly. 

If  you  convert  numeric  fields  to  character  fields,  dBASE  IV  will  convert 
numbers  from  the  numeric  fields  to  character  strings.  If  you  convert  a  char¬ 
acter  field  to  a  numeric  field,  dBASE  IV  will  convert  numeric  characters  in 
each  record  to  digits  until  it  encounters  a  non-numeric  character.  If  the  first 
character  in  a  character  field  is  a  letter,  the  converted  numeric  field  will 
contain  zero. 

You  can  convert  logical  fields  to  character  fields,  or  vice  versa.  You  cannot 
convert  logical  fields  to  numeric  fields.  You  can  also  convert  character 
strings  which  are  formatted  as  a  date  (for  example,  mm/dd/yy  or  mm-dd-yy) 
to  a  date  field,  or  convert  date  fields  to  character  fields. 

If  you  modify  the  field  name,  length,  or  type  of  any  fields  that  have  an  associ¬ 
ated  tag  in  the  production  .mdx  file,  the  tag  is  rebuilt. 

If  you  create  a  new  database  file  or  modify  an  existing  file,  you  must  use 
the  SQL  DBDEFINE  command  before  using  the  file  in  SQL  mode.  The 
DBDEFINE  command  updates  the  system  catalogs  that  SQL  uses  to  access 
the  file. 


See  Also 

APPEND  FROM,  APPEND  MEMO,  COPY  STRUCTURE,  COPY  STRUCTURE 
EXTENDED,  CREATE  FROM,  SET  BLOCKSIZE,  SET  SAFETY,  SET  SQL 
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CREATE  FROM  forms  a  new  database  file  from  the  structure  created  with 
the  COPY  STRUCTURE  EXTENDED  command. 


Syntax 

CREATE  <  filename  >  FROM  <  extended  structure  file  > 


This  command  is  most  often  used  in  application  programs  in  conjunction 
with  the  COPY  STRUCTURE  EXTENDED  command.  CREATE  FROM  creates 
a  database  file  from  the  extended  structure  file,  without  using  the  interactive 
CREATE  or  MODIFY  STRUCTURE  commands. 

The  file  created  with  CREATE  FROM  becomes  the  active  database  file  in  the 
currently  selected  work  area.  If  the  CREATE  FROM  operation  fails  for  any 
reason,  no  database  file  will  be  open  in  the  current  work  area. 


Tip 

Do  not  use  the  letters  A  through  J,  or  the  letter  M,  as  database  filenames, 
because  they  are  reserved  as  default  alias  names.  You  can,  however,  use  AA 
(for  example)  as  a  filename. 


Example 

In  this  example,  you  use  the  COPY  STRUCTURE  EXTENDED  command  to 
create  the  Newnames  database  file  from  Client. dbf.  Then  you  create  a  new 
database  file  with  the  same  structure  as^Client.dbf,  using  CREATE  FROM. 
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.  USE  Client 

.  (IfY  S7RUC71RE  EXTENDED  TO  fewiames 
.  USE  Msuiames 

.  CREATE  Ncl  ient  FROM  New&res 
.  DISPLAY  STRUCTURE 

Structure  for  database:  C:\C8ASE\NCLI0fl'.D0F 
Nurber  of  data  records:  0 
CDate  of  last  ipcfete  :  11/05/87 


Field 

Field  Name 

Type 

Width  Dec 

Index 

1 

CLIBrUD 

Character 

6 

Y 

2 

CLIBJT 

Character 

3D 

Y 

3 

LASTNAAE 

Character 

15 

N 

4 

FIRSTNAft 

Character 

15 

N 

5 

ADORESS 

Character 

30 

N 

6 

CITY 

Character 

20 

N 

7 

STATE 

Character 

2 

N 

8 

ZIP 

Character 

10 

N 

9 

PhCNE 

Character 

13 

N 

10 

CUBLHIST 

Memo 

10 

N 

**  Total  ** 

152 

1QIK  indexed  0  records  indexed 

1Qp£  indexed  0  records  indexed 


See  Also 

COPY,  COPY  STRUCTURE,  COPY  STRUCTURE  EXTENDED,  UST/DISPLAY 
STRUCTURE 
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CREATE  VIEW  FROM 
ENVIRONMENT 


CREATE  VIEW  FROM  ENVIRONMENT  builds  a  view  (.vue)  file  that  is 
compatible  with  dBASE  III  PLUS. 


Syntax 

CREATE  VIEW  <  .vue  filename  >  FROM  ENVIRONMENT 

Defaults 

Unless  otherwise  specified,  this  command  supplies  a  .vue  extension  to  the 
file  it  creates.  If  a  catalog  is  open,  and  SET  CATALOG  is  ON,  dBASE  IV  adds 
the  view  file  to  the  catalog. 


Usage 

The  dBASE  III  PLUS  CREATE  VIEW  FROM  ENVIRONMENT  command 
allowed  you  to  create  .vue  files  that  saved  information  about  the  current 
selection  of  work  areas;  open  database,  format,  and  index  files;  relations; 
field  lists;  and  filter  conditions.  The  dBASE  III  PLUS  SET  VIEW  command 
activated  the  environment  saved  in  the  .vue  file  by  opening  the  files  and  re* 
establishing  the  field  lists,  relations,  and  filter  conditions. 

Although  the  dBASE  IV  queries  designer,  which  is  accessible  from  the 
CREATE/MODIFY  QUERY/VIEW  command,  provides  much  more  capability 
than  .vue  files  allowed,  dBASE  IV  also  allows  you  to  create  .vue  files  for 
compatibility  with  dBASE  III  PLUS  applications. 

CREATE  VIEW  FROM  ENVIRONMENT  builds  a  view  (.vue)  file  that  saves 
the  following  information  from  the  currently  active  environment: 

■  All  open  database  files,  index  files,  and  the  work  area  of  each  file 

■  All  relations  between  the  database  files 

■  The  currently  selected  work  area  number 

■  The  active  field  list 

■  The  open  format  (.fmt)  file,  if  any 

■  Filter  conditions  in  effect 

You  must  open  the  files  and  establish  the  field  lists,  filter  conditions,  and 
relations  before  using  CREATE  VIEW  FROM  ENVIRONMENT. 

SET  VIEW  to  a  .vue  file  will  activate  the  view  that  CREATE  VIEW  FROM 
ENVIRONMENT  saved. 
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CREATE  VIEW  FROM  ENVIRONMENT 


To  deactivate  the  view  file,  open  a  different  view  file  or  type  CLOSE 
DATABASES.  This  closes  the  open  database  files  and  their  associated  files 
that  form  the  view  file. 


See  Also 

SELECT,  SET  HELDS,  SET  FORMAT,  SET  INDEX,  SET  RELATION,  SET 
VIEW,  USE 
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APPLICATION 


CREATE/MODIFY  APPLICATION  gives  you  access  to  the  dBASE  IV  Applica¬ 
tions  Generator,  which  generates  the  code  needed  to  tie  objects,  such  as 
database  files,  index  files,  queries,  reports,  forms,  menus,  and  lists,  together 
in  one  application. 


Syntax 

CREATE/MODIFY  APPLICATION  <  filenames-  /? 

Defaults 

You  must  provide  a  filename  for  the  application,  or  use  the  ?  (query  clause), 
in  the  command  line.  If  you  provide  an  application  filename  and  are  creat¬ 
ing  a  new  application,  dBASE  IV  uses  this  name  in  the  Application  Defini¬ 
tion  dialog  box.  You  can,  however,  change  the  application  name  in  the 
dialog  box. 


Usage 

The  CREATE  APPLICATION  and  MODIFY  APPLICATION  commands  are 
identical.  The  presence  of  an  application  object  (.app)  file,  rather  than  the 
command  verb  you  use,  determines  whether  a  create  or  modify  operation 
will  occur.  If  the  .app  object  file  exists,  this  command  allows  you  to  modify 
it;  if  the  .app  object  file  does  not  exist,  this  command  allows  you  to  create  a 
new  one. 
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Besides  the  application  object,  you  may  create  the  following  objects  with  the 
Applications  Generator: 


Table  2-4  Objects  created  with  the  Applications  Generator 


Object 

Extension 

Description 

Horizontal  bar  menu 

.bar 

Menu  items  that  appear  across  the 
screen 

Pop-up  menu 

.pop 

Menu  items  that  appear  vertically  in  a 
frame 

Files  lists 

.fil 

A  list  of  files  from  which  you  may 
choose 

Structure  list 

.str 

A  list  of  fields  in  the  current  database 
file  or  view  from  which  you  may 
choose 

Values  list 

.val 

A  list  of  values  that  a  field  may  contain 

Batch  process 

.bch 

A  series  of  actions  associated  with  a 
menu  item  or  list  that  your  application 
may  perform 

If  a  catalog  is  open,  only  the  application  (.app)  object  that  you  create  is 
added  to  the  catalog.  Any  other  objects  that  you  create  (.bar,  .pop,  .fil,  .str, 
.val,  or  .bch)  are  added  to  the  current  subdirectory. 


Options 

If  a  catalog  is  open,  the  ?  symbol  queries  the  catalog  for  all  available  .app 
object  files.  If  a  catalog  is  not  open,  the  ?  symbol  presents  all  .app  object  files 
on  the  disk.  You  can  then  choose  the  application  you  wish  to  modify,  or  cre¬ 
ate  a  new  one. 


Special  Cases 

You  may  also  enter  the  Applications  Generator  from  the  Control  Center.  If 
you  enter  the  Applications  Generator  from  CREATE/MODIFY  APPLICATION, 
however,  the  exit  options  return  control  to  the  dot  prompt  or  the  next  com¬ 
mand  in  a  program  file,  not  to  the  Control  Center. 
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If  you  select  the  <  create  >  marker  from  the  Applications  panel  in  the 
Control  Center,  you  can  choose  to  create  a  new  application  with  either 
the  program  editor  or  the  Applications  Generator.  CREATE/MODIFY 
APPLICATION,  however,  brings  you  directly  to  the  Applications  Generator. 
To  reach  the  program  editor,  you  must  type  MODIFY  COMMAND. 


See  Also 

Using  the  d BASE  IV  Applications  Generator  contains  further  information 
about  what  applications  are  and  how  to  create  them. 
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CREATE/MODIFY 

LABEL 


CREATE/MODIFY  LABEL  gives  you  access  to  the  label  designer.  The  label 
designer  allows  you  to  create  label  form  (.lbl)  files  using  the  fields  specified 
in  the  current  database  file  or  in  other  related  database  files. 


Syntax 

CREATE/MODIFY  LABEL  <  filename>  /? 


Defaults 

Unless  you  specify  otherwise,  dBASE  IV  creates  the  file  with  a  .lbl  extension. 
CREATE  LABEL  will  always  generate  a  file  with  an  .Ibg  file  extension,  how- 
ever,  and  you  cannot  override  this.  If  a  catalog  is  open  and  SET  CATALOG  is 
ON,  dBASE  IV  adds  the  label  file  to  the  catalog. 


Usage 

Use  the  CREATE  LABEL  command  to  create  a  new  label  form  (.lbl)  file.  The 
.lbl  file  contains  all  the  information  needed  to  set  up  the  environment,  to  set 
up  a  display  of  the  label  design  which  can  later  be  changed,  and  to  print 
labels  using  data  from  a  database  file  or  view. 

You  specify  the  size  of  the  label  you  want  to  create  and  the  number  of 
printed  lines  on  each  label.  These  values  should  match  the  label  forms  or 
paper  on  which  you  want  to  print. 

The  CREATE  LABEL  and  MODIFY  LABEL  commands  are  identical.  The  pres¬ 
ence  of  a  label  form  file,  n.ther  than  the  command  verb  you  use,  determines 
whether  a  create  or  modify  operation  will  occur.  If  the  .lbl  file  exists,  this 
command  modifies  it;  if  the  .lbl  file  does  not  exist,  this  command  creates 
one. 

Using  CRE ATE/ MODIFY  LABEL,  you  select  and  lay  out  the  information  you 
want  on  each  label.  When  you  save  the  label  form,  CREATE/MODIFY  LABEL 
creates  a  file  containing  the  dBASE  IV  code  that  prints  labels.  This  file  has 
the  same  name  as  the  label  form  file,  but  with  an  .Ibg  file  extension.  When 
you  first  print  labels  with  the  LABEL  FORM  command,  an  .lbo  file,  which 
contains  the  compiled  object  code  of  the  .Ibg  file,  is  written  to  disk.  The 
LABEL  FORM  command  subsequently  uses  this  .lbo  file  whenever  you  print 
labels  with  this  form. 
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CREATE/MODIFY  LABEL 


Options 

If  a  catalog  is  open,  the  ?  symbol  queries  the  catalog  for  all  available  .lbl  files 
associated  with  the  active  database  file.  If  a  catalog  is  not  open,  the  ?  symbol 
presents  all  .lbl  files  on  the  disk.  You  can  then  choose  the  label  form  file  you 
wish  to. modify. 

Special  Cases 

You  may  also  enter  the  label  designer  from  the  Control  Center.  If  you  enter 
the  label  designer  from  CREATE/MODIFY  LABEL,  however,  the  exit  options 
return  control  to  the  dot  prompt  or  the  next  command  in  a  program  file,  not 
to  the  Control  Center. 

If  you  erase  the  label  form  (.lbl)  file,  you  will  not  be  able  to  use  the  CREATE 
or  MODIFY  LABEL  commands  to  edit  the  file.  An  attempt  to  edit  the  file  will 
generate  a  new  label  file  if  the  old  label  file  cannot  be  found. 

Although  you  can  use  MODIFY  COMMAND  or  a  text  editor  to  make  changes 
directly  to  the  generated  label  (.lbg)  file,  the  changes  will  not  be  made  to  the 
.lbl  or  .Ibo  files.  You  must  delete  the  old  .lbo  file,  and  use  LABEL  FORM  to 
compile  a  new  .lbo  file. 

If  you  modify  a  label  form  (.lbl)  file  that  was  created  in  dBASE  III  PLUS,  the 
file  is  converted  to  dBASE  IV  format,  and  the  original  dBASE  III  PLUS  .lbl 
file  is  saved  with  an  .lb3  extension.  You  cannot  run  dBASE  IV  labels  in 
dBASE  III  PLUS. 


See  Also 

LABEL  FORM,  SET  CATALOG,  SET  SAFETY,  SET  VIEW,  TRIM() 

Using  the  Menu  System  contains  further  information  on  creating  labels  with 
the  dBASE  IV  label  designer. 
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CREATE/MODIFY 

QUERY/VIEW 


CREATE/ MODIFY  QUERY  or  CREATE/ MODIFY  VIEW  gives  you  access  to 
the  queries  design  screen,  which  allows  you  to  create  query  (.qbe)  files  that 
extract  records  matching  specified  conditions,  or  to  create  update  query 
(.upd)  files  that  can  modify  records  in  the  database  file. 


Syntax 

CREATE/MODIFY  QUERY  <  filename  >  /? 
or 

CREATE/MODIFY  VIEW  <  filename  >  /? 


Defaults 

dBASE  IV  will  always  write  the  query  file  with  a  .qbe  or  .upd  extension.  If  a 
catalog  is  open  and  SET  CATALOG  is  ON,  the  query  file  is  added  to  the 
catalog. 


Usage 

A  .qbe  file  allows  only  the  records  that  meet  the  specified  conditions  to  be 
displayed  when  subsequent  commands  are  issued.  A  .upd  file  contains 
instructions  for  updating  records  in  the  database  file. 

The  new  query  file  will  have  a  .upd  extension  only  if  you  placed  an  update 
operator  under  the  name  of  the  file  in  the  design  screen’s  file  skeleton. 

You  may  use  either  the  C  IE  ATE/  MODIFY  QUERY  or  CREATE/MODIFY 
VIEW  command  to  access  the  queries  design  screen. 

The  CREATE  and  MODIFY  forms  of  the  command  are  identical.  The  pres¬ 
ence  of  a  query  (either  .qbe  or  upd)  file,  rather  than  the  command  verb  you 
use,  determines  whether  a  create  or  modify  operation  will  occur.  If  the  .qbe 
or  .upd  file  exists,  this  command  asks  if  you  want  to  modify  it;  if  the  .qbe  or 
.upd  file  does  not  exist,  this  command  creates  one. 

dBASE  IV  views  are  a  superset  of  the  queries  and  views  created  in  earlier 
versions  of  dBASE.  The  .vue  files  created  by  earlier  versions  can  be  read  by 
this  dBASE  IV  command,  and  new  .qbe  files  will  be  created  from  them.  The 
new  .qbe  files  cannot,  however,  be  read  by  earlier  versions  of  dBASE. 

If  you  do  not  specify  an  extension,  the  command  first  looks  for  a  .qbe  or 
.upd  file  previously  created  by  the  queries  design  screen.  If  a  .qbe  or  upd 
file  cannot  be  found,  this  command  looks  for  a  .vue  file  created  with  an 
earlier  version  of  dBASE.  If  a  .vue  file  also  cannot  be  found,  this  command 
creates  a  new  file  with  either  a  .qbe  or  .upd  extension. 
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CREATE/MODIFY  QUERY/VIEW 


When  you  first  use  SET  VIEW  to  activate  a  ,qbe  file,  or  perform  the  query 
with  F2  D^TA,  a  .qbo  file  is  written  to  disk.  The  SET  VIEW  command  subse¬ 
quently  uses  the  .qbo  file  whenever  you  activate  this  query.  When  you  first 
use  DO  to  perform  the  update  query,  or  perform  the  update  from  the  queries 
design  menu  bar,  a  .upo  file  is  written  to  disk.  You  must  specify  this  .upo 
extension  whenever  you  want  to  DO  the  update  query. 


Options 

If  a  catalog  is  open,  the  ?  symbol  queries  the  catalog  for  all  available  .qbe 
and  .upd  files  that  are  associated  with  the  active  database  file.  If  a  catalog  is 
not  open,  the  ?  symbol  presents  all  .qbe  and  .upd  files  on  the  disk.  You  can 
then  choose  the  query  file  you  wish  to  modify. 

Special  Cases 

You  may  also  enter  the  query  designer  from  the  Control  Center.  If  you  enter 
the  query  designer  from  CREATE/ MODIFY  QUERY,  however,  the  exit 
options  return  control  to  the  dot  prompt  or  the  next  command  in  a  program 
file,  not  to  the  Control  Center. 

If  you  erase  the  .qbe  or  upd  files,  you  will  not  be  able  to  use  the 
CREATE/MODIFY  QUERY/ VIEW  command  to  edit  these  files.  An  attempt 
to  edit  these  files  will  generate  new  query  files  if  the  old  query  files  cannot 
be  found. 

Although  you  can  use  MODIFY  COMMAND  or  a  text  editor  to  make  changes 
directly  to  the  .qbe  or  .upd  files,  the  changes  will  not  be  made  to  the  .qbo  or 
.upo  files.  You  must  delete  the  old  object  files,  and  use  SET  VIEW  or  DO  to 
compile  new  object  files. 


See  Also 

SET  CATALOG,  SET  FILTER,  SET  SAFETY,  SET  VIEW 

Using  the  Menu  System  contains  further  information  on  creating  queries  with 
the  query  designer. 
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CREATE/MODIFY 

REPORT 


CREATE/MODIFY  REPORT  gives  you  access  to  the  report  designer,  which 
allows  you  to  create  report  form  (.frm)  files  using  the  fields  specified  in  the 
current  database  file  or  in  other  related  database  files. 


Syntax 

CREATE/MODIFY  REPORT  <  filename  >  /? 

Defaults 

Unless  you  specify  otherwise,  dBASE  IV  creates  the  file  with  an  .frm  exten¬ 
sion.  CREATE  REPORT  will  always  generate  a  file  with  an  .frg  file  extension, 
however,  and  you  cannot  override  this.  If  a  catalog  is  open  and  SET 
CATALOG  is  ON,  the  report  form  file  is  added  to  the  catalog. 


Usage 

Use  the  CREATE/MODIFY  REPORT  command  to  create  a  new  report  form 
(.frm)  file.  The  report  form  file  contains  all  the  information  needed  to  set  up 
a  display  of  the  report  design  which  can  later  be  changed,  and  to  print 
reports  using  data  from  a  database  file  or  view. 

The  CREATE  REPORT  and  MODIFY  REPORT  commands  are  identical.  The 
presence  of  a  report  form  (.frm)  file,  rather  than  the  command  verb  you  use, 
determines  whether  a  create  or  modify  operation  will  occur.  If  the  .frm  file 
exists,  this  command  modifies  it;  if  the  .frm  file  does  not  exist,  this  command 
creates  one. 

Using  CREATE  or  MODIFY  REPORT,  you  may  select  the  information  you 
want  the  report  to  contain,  place  fields  where  you  would  like  them  to  print, 
group  information  together,  and  calculate  statistical  information  on  numeric 
expressions.  When  you  save  the  report  form,  CREATE/MODIFY  REPORT  cre¬ 
ates  a  file  containing  the  dBASE  IV  code  that  prints  a  report.  This  file  has  the 
same  name  as  the  report  form  file,  but  with  an  .frg  file  extension.  When  you 
print  the  report  with  the  REPORT  FORM  command,  an  .fro  file,  which  con¬ 
tains  the  compiled  object  code  of  the  .frg  file,  is  written  to  disk.  The 
REPORT  FORM  command  subsequently  uses  this  .fro  file  whenever  you 
print  a  report  with  this  form. 


Options 

If  a  catalog  is  open,  the  ?  symbol  queries  the  catalog  for  all  available  .frm 
files  associated  with  the  active  database  file.  If  a  catalog  is  not  open,  the  ? 
symbol  presents  all  .frm  files  on  the  disk.  You  can  then  choose  the  report 
form  file  you  wish  to  modify,  or  create  a  new  one. 
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CREATE/MODIFY  REPORT 


Special  Cases 

You  may  also  enter  the  report  designer  from  the  Control  Center.  If  you  enter 
the  report  designer  from  CREATE/MODIFY  REPORT,  however,  the  exit 
options  return  control  to  the  dot  prompt  or  the  next  command  in  a  program 
file,  not  to  the  Control  Center. 

If  you  erase  the  report  form  (.frm)  file,  you  will  not  be  able  to  use  the 
CREATE  or  MODIFY  REPORT  commands  to  edit  the  file.  An  attempt  to  edit 
the  file  will  generate  a  new  report  file  if  the  old  report  file  cannot  be  found 

Although  you  can  use  MODIFY  COMMAND  or  a  text  editor  to  make  changes 
directly  to  the  generated  report  form  (.frg)  file,  the  changes  will  not  be  made 
to  the  .frm  or  .fro  files  You  must  delete  the  old  .fro  file,  and  use  REPORT 
FORM  to  compile  a  new  .fro  file. 

If  you  modify  a  report  form  (.frm)  file  that  was  created  in  dBASE  III  PLUS, 
the  file  is  converted  to  dBASE  IV  format,  and  the  original  dBASE  III  PLUS 
.frm  file  is  saved  with  an  .fr3  extension.  You  cannot  run  dBASE  IV  reports  in 
dBASE  III  PLUS. 


See  Also 

REPORT  FORM,  SET  CATALOG,  SET  DESIGN,  SET  SAFETY,  SET  VIEW 

Using  the  Menu  System  contains  further  information  on  creating  reports  with 
the  report  designer. 
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CREATE/MODIFY 

SCREEN 


CREATE/MODIFY  SCREEN  gives  you  access  to  the  forms  design  screen, 
which  allows  you  to  create  custom  screen  forms.  These  screen  forms  deter¬ 
mine  the  way  fields  and  other  data  appear  on  the  screen  when  you  use  a  full¬ 
screen  editing  command,  such  as  EDIT  or  APPEND. 

Syntax 

CREATE/MODIFY  SCREEN  <  filename  >  II 


Defaults 

dBASE  IV  will  always  write  the  screen  file  with  an  .scr  extension,  and  will 
always  generate  a  format  file  with  an  .fmt  extension.  If  a  catalog  is  open  and 
SET  CATALOG  is  ON,  the  query  and  format  files  are  added  to  the  catalog. 


Usage 

Use  the  CREATE  SCREEN  command  to  create  a  screen  (  scr)  file  and  new 
format  (.fmt)  file.  The  screen  file  contains  the  information  in  a  form  that  you 
can  later  edit,  and  the  format  file  contains  the  dBASE  IV  commands  to  dis¬ 
play  the  data  on  the  screen.  When  you  design  or  modify  a  screen,  you  are 
working  with  the  screen  file. 

The  CREATE  SCREEN  and  MODIFY  SCREEN  commands  are  identical.  The 
presence  of  a  screen  (.scr)  file,  rather  than  the  command  verb  you  use, 
determines  whether  a  create  or  modify  operation  will  occur.  If  the  .scr  file 
exists,  this  command  modifies  it;  if  the  .scr  file  does  not  exist,  this  command 
creates  one  and  generates  u  new  format  file. 

Using  CREATE  or  MODIFY  SCREEN,  you  can  position  fields  on  the  screen; 
display  calculated  fields  and  memory  variables;  and  include  additional  text, 
boxes,  and  lines.  When  you  save  the  screen  form,  CREATE/MODIFY 
SCREEN  creates  a  format  file  containing  @  commands  to  display  and  allow 
editing  of  the  data.  The  format  file  has  the  same  name  as  the  screen  file,  but 
with  an  .fmt  file  extension.  When  you  first  use  the  format  file  with  the  SET 
FORMAT  command,  an  .fmo  file,  which  contains  the  compiled  object  code  of 
the  .fmt  file,  is  written  to  disk.  dBASE  IV  subsequently  uses  this  fmo  file 
whenever  you  use  SET  FORMAT  with  a  full-screen  editing  command. 

You  can  open  or  close  the  format  file  you  created  at  any  time  with  the  SET 
FORMAT  command. 
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CREATE/MODIFY  SCREEN 


Options 

If  a  catalog  is  open,  the  ?  symbol  queries  the  catalog  for  all  available  .scr 
files  associated  with  the  active  database  file.  If  a  catalog  is  not  open,  the  ? 
symbol  presents  all  .scr  files  on  the  disk.  You  can  then  choose  the  screen  file 
you  wish  to  modify. 

Special  Cases 

Unlike  earlier  versions  of  dBASE,  CREXTE/MODIFY  SCREEN  does  not  make 
any  changes  to  the  physical  structure  of  the  database  file. 

If  you  erase  the  screen  file,  you  will  not  be  able  to  use  the  CREATE  or 
MODIFY  SCREEN  commands  to  edit  the  file.  An  attempt  to  edit  the  file  will 
generate  a  new  screen  file  if  the  old  screen  file  cannot  be  found. 

Although  you  can  use  MODIFY  COMMAND  or  a  text  editor  to  make  changes 
directly  to  the  format  (.fmt)  file,  the  changes  will  not  be  made  to  the  .scr  or 
.fmo  files.  You  must  delete  the  old  .fmo  file,  and  use  SET  FILTER  to  compile 
a  new  .fmo  file. 

If  you  modify  a  screen  (  scr)  file  that  was  created  in  dBASE  III  PLUS,  the  file 
is  converted  to  dBASE  IV  format,  and  the  original  dBASE  III  PLUS  scr  file  is 
saved  with  an  .sc3  extension.  You  cannot  modify  dBASE  IV  screen  files  in 
dBASE  III  PLUS. 

The  format  file  that  CREATE/MODIFY  SCREEN  generates  has  literal  strings 
embedded  in  double  quote  marks.  This  could  affect  the  display  if  you  have 
double  quote  marks  in  your  data.  If  you  cannot  remove  the  double  quotes 
from  your  data,  you  may  ERASE  the  .fmo  file,  change  the  literal  delimiters  in 
the  .fmt  file  with  the  MODIFY  COMMAND  program  editor,  and  SET  FILTER 
so  that  the  new  .fmt  file  is  compiled  to  an  .fmo  file. 


See  Also 

@,  APPEND,  BROWSE,  EDIT,  INSERT,  SET  CATALOG,  SET  FORMAT,  SET 
SAFETY,  SET  VIEW 

Using  the  Menu  System  contains  further  information  on  using  the  screen 
designer. 
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DEACTIVATE  MENU 


The  DEACTIVATE  MENU  comm  and  deactivates  the  active  bar  menu  and 
erases  it  from  the  screen,  while  leaving  it  in  memory.  It  has  no  effect  when 
executed  from  the  dot  prompt.  It  must  be  used  as  part  of  an  ON  SELECTION 
statement,  because  this  is  the  only  way  it  can  be  executed  with  an  active 
menu. 


Syntax 

DEACTIVATE  MENU 

Usage 

This  command  does  not  require  a  menu  name;  it  deactivates  the  only  active 
menu  and  erases  it  from  the  screen.  The  screen  returns  to  displaying  what¬ 
ever  is  under  the  deactivated  menu. 

A  deactivated  menu  is  not  released  from  memory;  you  can  reactivate  it  at 
any  time  with  the  ACTIVATE  MENU  command. 

DEACTIVATE  MENU  returns  control  to  the  level  at  which  the  menu  was 
ACnVATEd.  If  an  ON  PAD  is  in  effect,  this  command  will  also  deactivate  all 
descendent  popups  and  menus. 


Example 


This  example  defines  a  bar  menu  with  two  selections.  It  can  display  a  direc¬ 
tory  listing  or,  alternately,  deactivate  itself: 


.  DEFVE mi!  Test  tESSAGE  'Test0 
.  DEFINE  PAD  Dir  OF  Test  Ff&PT  " Directory0  AT  OJJ 
.  DEFINE  PAD  Deac  OF  Test  Pf&PT  "Deactivate"  AT  0,15 
.  CN  SELECTION  FAD  Dir  OF  Test  DIR 
.  CN  SELECTION  FAD  Deac  OF  Test  DEACTIVATE  f&U 


See  Also 

ACTIVATE  MENU,  DEFINE  MENU,  RELEASE  MENUS 
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DEACTIVATE  POPUP 


The  DEACTIVATE  POPUP  command  erases  the  active  pop-up  menu  from  the 
screen  while  leaving  it  intact  in  memory.  Any  text  that  was  covered  by  the 
popup  is  displayed  again. 


Syntax 

DEACTIVATE  POPUP 


Usage 

DEACTIVATE  POPUP  has  no  effect  when  executed  from  the  dot  prompt, 
because  when  a  popup  is  active,  you  can  be  only  in  the  active  popup.  If  you 
press  the  Esc  key,  you  bypass  this  command,  deactivate  the  popup,  and 
return  to  the  dot  prompt.  Therefore,  you  can  use  this  command  only  as  part 
of  an  ON  SELECTION  statement,  because  this  is  the  only  way  an  active 
popup  can  be  deactivated. 

Example 

This  example  shows  a  popup  called  Exit_pop,  with  two  options.  Either 
option  calls  a  procedure  that  evaluates  the  user’s  selection.  Notice  that  the 
popup  is  activated  as  one  of  the  options  of  the  procedure  file. 

.  DEFINE  PCFLP  Exitjxp  FROM  7,  10 
.  DEFIfC  BAR  1  OF  Exitjxp  "GUT 
.  DEFINE  BAR  2  OF  Exitjxp  ", Exit  to  dot  pronpf 
.  CM  SELECTION  POFTJP  Exitjxp  DO  Exitjroc 

PROCEDURE  Exitjroc 
DO  CASE 

CASE  BARO  =  1 
GLUT 

CASE  BARO  =2 
DEACTIVATE  PORP 
BDCASE 


See  Also 

ACTIVATE  POPUP,  DEFINE  POPUP 
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DEACTIVATE 

WINDOW 


The  DEACTIVATE  WINDOW  command  deactivates  specified  windows  and 
removes  them  from  the  screen,  without  releasing  them  from  memory. 


Syntax 

DEACTIVATE  WINDOW  <  window  name  list /  ALL 

Usage 

This  command  deactivates  windows  in  the  window  name  list  by  erasing  them 
from  the  screen.  The  windows  are  not  released  from  memory,  and  you  can 
bring  them  back  to  the  screen  with  the  ACTIVATE  WINDOW  command. 

When  you  DEACTIVATE  a  window,  any  window  that  was  previously 
ACTIVATEd  becomes  current  again.  DEACTIVATEing  all  windows  with  the 
ALL  option  restores  full-screen  mode. 

See  Also 

ACTIVATE  WINDOW,  DEFINE  WINDOW,  RESTORE  WINDOW, 

SAVE  WINDOW 
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DEBUG 


DEBUG  gives  you  access  to  the  dBASE  IV  program  debugger. 

Syntax 

DEBUG  <  filename  >  /<  procedure  name>  [WITH  <  parameter  list  >  ] 


Usage 

This  command,  like  DO,  executes  a  program  or  procedure,  but  also  invokes 
dBASE  IV’s  full-screen  debugger. 

The  debugger  screen  contains  four  windows  that  allow  you  to  run  a  program 
or  procedure  and  see  the  commands  as  they  are  executing,  edit  the  program 
or  procedure,  set  breakpoints  to  halt  program  execution,  and  display  the 
results  of  expressions  while  the  program  is  executing. 

The  screen  is  divided  into  a  debug  window,  an  edit  window,  a  breakpoint 
window,  and  a  display  window. 

The  debug  window,  at  the  bottom  of  the  screen,  displays  the  current  work 
area,  database  file,  program  file,  procedure,  record  number,  line  number, 
master  index  file,  and  the  ACTION:  prompt.  Pressing  Esc  or  Ctrl-End  any¬ 
where  on  the  screen  returns  you  to  the  ACTION:  prompt  in  the  debug 
window. 

If  you  enter  an  E  at  the  ACTION:  prompt,  the  edit  window  becomes  active. 
This  window,  at  the  top  of  the  screen,  shows  the  program  or  procedure 
being  executed.  When  the  edit  window  is  active,  you  can  access  the 
dBASE  IV  editor  and  make  changes  to  the  program.  You  must  save  the  file 
to  avoid  losing  the  changes.  Once  the  changes  are  made,  the  debugger  con¬ 
tinues  execution  from  the  new  file.  The  debugger  may  execute  a  command 
line  that  is  not  the  line  you  expect  to  be  executed,  depending  on  how  you 
changed  the  file. 

If  you  enter  a  B  at  the  ACTION:  prompt,  the  breakpoint  window,  on  the 
right  side  of  the  screen,  becomes  active.  You  may  enter  one  or  more  condi¬ 
tions  in  the  breakpoint  window  that  will  be  evaluated  after  each  line  of  code 
is  executed.  If  one  of  the  conditions  evaluates  to  true  (.T.),  the  program  is 
halted  and  the  ACTION:  prompt  becomes  active. 

If  you  enter  a  D  at  the  ACTION:  prompt,  the  display  window,  on  the  left  side 
of  the  screen,  becomes  active.  You  may  enter  dBASE  expressions  on  the  left 
of  this  window.  These  expressions  are  evaluated  after  each  line  of  code  is 
executed,  and  the  results  are  displayed  on  the  right  of  the  display  window. 
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DEBUG 


At  the  ACTION:  prompt,  you  may  also  enter  the  following: 

■  L  Line  —  Begin  execution  at  a  specified  line. 

■  N  Next  —  Execute  the  next  command  in  the  current  program  or 
procedure,  or  in  the  calling  program  or  procedure,  then  return  to  the 
ACTION:  prompt.  If  there  is  a  DO  in  the  current  procedure,  the  called 
procedure  will  execute  outside  the  debugger  environment,  although  the 
breakpoint  watch  will  remain  in  effect.  If  you  precede  the  N  with  a  num¬ 
ber,  you  direct  the  debugger  to  execute  that  number  of  commands  in  the 
current  procedure  before  returning  to  the  ACTION:  prompt. 

■  P  Program  Trace  —  Show  the  program  trace  inform ation,  which 
includes  the  current  program,  procedure,  and  line  number. 

■  Q  Quit  —  Quit  the  debugger  and  cancel  the  program. 

■  R  Run  —  Run  the  program  until  a  breakpoint  or  error  is  encountered. 

■  S  Step  —  Execute  the  next  command,  then  return  to  the  ACTION: 
prompt.  If  you  precede  the  S  with  a  number,  you  direct  the  debugger 
to  step  through  that  number  of  commands  before  returning  to  the 
ACTION:  prompt.  Unlike  N,  procedures  called  from  the  current  proce¬ 
dure  are  executed  within  the  debugger  environment. 

■  X  Exit  —  Exit  the  program  and  return  to  the  dot  prompt.  From  the  dot 
prompt,  RESUME  passes  control  back  to  the  debugger. 

■  —  Execute  either  IS  or  1 N.  If  a  Step,  S,  was  last  executed,  ♦♦  will 
execute  a  IS.  If  a  Next,  N,  was  last  executed,  will  execute  a  IN.  By 
default,  ♦*  executes  a  IS. 

FI  Help  and  F9  Zoom  are  toggle  keys: 

Pressing  FI  Help  anywhere  on  the  screen  brings  up  or  removes  the  Help 
panel,  a  brief  description  of  the  debug  commands  you  can  enter  at  the 
ACTION:  prompt. 

Pressing(F9Zoom)removes  the  debugger  windows  from  the  screen  to  show 
the  underlying  screen  information,  or  replaces  the  debugger  windows  on  the 
screen. 


Options 

The  WITH  parameter  allows  you  to  pass  parameters  in  the  same  way  as  DO. 
The  parameter  list  may  contain  any  valid  dBASE  IV  expressions. 
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COMPILE,  DO,  MODIFY  COMMAND,  SET  DEBUG,  SET  ECHO, 
SET  PROCEDURE,  SET  STEP,  SET  TALK,  SET  TRAP 
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DECLARE 


DECLARE  creates  one-  or  two-dimensional  arrays  of  memory  variables. 


Syntax 

DECLARE  <  array  name  1  >  [  <  number  of  rows  > 

{,<  number  of  columns>  }]  {,<  array  name  2 >  [ <  num ber  of  rows  > 
{,<  number  of  columns  >  }]  ...} 

In  this  paradigm,  the  curly  braces  indicate  optional  items.  The  square  brack¬ 
ets  are  a  required  part  of  the  DECLARE  command  syntax 


Defaults 

The  array  is  public  if  the  DECLARE  command  is  entered  at  the  dot  prompt, 
private  if  the  command  is  in  a  program  file.  You  may  create  a  public  array  in 
a  program  file  with  the  PUBLIC  command. 

FLBLIC  ARRAY  RsrtsC6,2] 

creates  a  public  array,  called  Parts,  if  the  command  is  used  in  a  program  file. 
DECLARE  PartsC6,23 

creates  a  private  array,  called  Parts,  if  you  use  the  command  in  a  program 
file.  If  you  use  the  command  from  the  dot  prompt,  the  array  is  public. 

Usage 

The  array  definition  list  consists  of  the  array  names  and  array  dimensions. 
Like  memory  variables,  array  names  can  be  up  to  ten  characters  long.  They 
can  contain  letters,  numbers,  and  underscores.  They  must  begin  with  a  letter 
and  cannot  contain  embedded  blank  spaces.  The  array  name  cannot  be  the 
same  as  a  dBASE  IV  command. 

The  array  dimensions  consist  of  one  or  two  numbers  in  square  brackets.  The 
first  number  is  the  number  of  rows  in  the  array,  the  second  is  the  number  of 
columns  in  the  array.  If  only  one  number  is  used,  the  array  is  one-dimen¬ 
sional.  If  two  are  used,  they  are  separated  by  a  comma  and  the  array  is  two- 
dimensional.  The  maximum  number  of  dimensions  is  two. 
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DECLARE 


.  DECLARE  CcstC15J 

creates  a  one-dimensional  array.  Cost  is  the  array  name,  and  it  contains  fif¬ 
teen  elements. 

.  DECLARE  ItemsCS^U 

creates  a  two-dimensional  array  called  Items,  which  has  eight  rows  and  three 
columns.  It  contains  24  elements. 

The  DECLARE  command  creates  a  set  of  memory  variables,  each  of  which 
initially  contains  a  logical  false  (.F.)  value.  Array  elements  assume  a  data 
type  only  when  information  is  STOREd  to  them.  For  example: 

.  STCRE  {6/15/88}  TO  H±>teC2^J 

initializes  the  element  Mdate[2,2]  with  a  date  value. 

One  array  may  contain  elements  of  different  data  types. 

The  array  name  uses  one  slot  from  the  same  memvar  pool  used  by  other 
memory  variables.  Each  array  element,  however,  does  not  use  a  slot  from 
this  memvar  pool,  but  is  stored  in  a  separate  block  allocated  to  hold  the  ele¬ 
ments  .  If  an  array  declaration  exceeds  available  memory,  the  error  message 
Insufficient  Memory  appears.  After  declaring  an  array,  the  elements  are 
treated  like  any  other  memory  variable.  The  elements  are  referred  to  by  their 
array  name  and  position  in  the  array,  beginning  from  left  to  right  and  top  to 
bottom.  For  example,  Cost[4]  or  Items[5,2]  are  sample  element  names. 

All  commands  and  functions  which  can  be  used  with  memory  variables  can 
also  be  used  with  array  elements,  as  long  as  the  array  has  been  declared  and 
the  element  is  within  the  range  of  the  array  declaration.  Some  commands, 
such  as  COPY  and  APPEND,  have  special  forms  (COPY  TO  ARRAY  and 
APPEND  FROM  ARRAY)  to  handle  arrays.  Commands  that  manipulate 
memory  variables  (such  as  CLEAR  ALL,  CLEAR  MEMORY,  LIST/DISPLA5f 
MEMORY,  RELEASE,  RESTORE,  and  SAVE)  support  arrays  as  well  as 
memory  variables. 

If  you  reference  array  coordinates  that  do  not  exist,  the  error  message  Bad 
array  dimension^)  appears.  If  you  reference  an  array  name  that  has  not 
been  DECLAREd,  the  message  Not  an  array  appears. 
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DECLARE 


Examples 

Using  the  Transact  database  file,  store  the  number  of  orders  and  the  sum  of 
the  Total.bill  field  to  an  array  called  Details: 

.  SET  TALK  OFF 
.  USE  Transact 
.  DECLARE  Detailsl2J 

.  CALCULATE  CNTO,  SUMCTotaU>iLL)  TO  ARRAY  Details 
.  ?  L TRIMCSTRCDeta ilsCIJ^JD),  ' orders  for  S  +  LTRIMCSTRCDetailsGO,^) 

12  orders  for  S1CO0O.CD 


Using  the  same  database  file,  in  a  program  file  use  two  arrays  to  detail  the 
breakdown  of  orders  by  Client,  id: 

USE  Transact  ORDER  Client-id 

DECLARE  0rdersC12,3]  8&  Declare  cue  rcw  for  each  client. 

DECLARE  Detai  IsCZ] 

Went  =  1 

DO  WILE  .NOT.  BDFO 

0rdersCMant,1]  =  ClientJd  8&  Save  ClientJd. 

CALCULATE  CNTO,  SUKTotaLbill)  TO  ARRAY  Details; 

WILE  ClientJd  =  0rdersCMnt,1] 

OrdersCMcnt,Z]  =  DetailsCID  8&  Save  cant  of  orders. 

0rdersCMant,3]  =  Detai lsC23  8&  Save  total  for  ClientJd. 

Went  =  Mint  +  1 
BDOO 

?  "Client  ID* ,  "Orders  AT  12,  "Total"  AT  24  8&  Colum  headings. 

Mclients  =  Mcnt  -  1 
Mont  =  1 

DO  WILE  Mcnt  <=  Clients 

?  0rdersCMcnt,1D,  STRfcrdersCMcnt^AO)  AT  10,; 

STR(0rdersOfcnt,3],9,2)  AT  20 
Mont  =  Mcnt  +  1 
0®OO 


See  Also 

APPEND,  AVERAGE,  CALCULATE,  CLEAR  ALL,  CLEAR  MEMORY,  COPY, 
COUNT,  LIST/ DISPLAY  MEMORY,  PUBLIC,  RELEASE,  RESTORE,  SAVE, 
SUM 
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DEFINE  BAR 


The  DEFINE  BAR  command  defines  a  single  option  in  a  pop-up  menu. 

Syntax 

DEFINE  BAR  <  line  number>  OF  <  popup  name>  PROMPT  <  expC> 
[MESSAGE  <  expC>  ]  [SKIP  [FOR  <  condition  >  ]  [NOSPACE]] 


Usage 

A  bar  is  a  single  prompt  or  option  that  appears  in  a  defined  pop-up  menu  or 
window.  To  use  DEFINE  BAR,  you  must  not  use  the  PROMPT  FIELD  options 
of  the  DEFINE  POPUP  command.  This  is  because  the  PROMPT  FIELD 
options  take  the  place  of  BARs  and  fill  a  defined  pop-up  window. 

Use  only  positive  whole  numbers  for  the  line  numbers;  fractional  line  num¬ 
bers  are  truncated. 

If  you  define  a  second  bar  prompt  for  a  line  number  that  already  has  a  bar 
prompt,  the  new  bar  prompt  overwrites  the  earlier  one. 

If  you  define  a  bar  for  a  number  that  exceeds  the  total  number  of  lines  found 
in  the  pop-up  window,  then  the  prompts  scroll  vertically  inside  the  pop-up 
window . 

If  a  BAR  value  is  missing,  that  row  in  the  popup  is  left  blank,  and  the  selec¬ 
tion  bar  skips  over  it. 

If  the  length  of  the  bar  prompt  exceeds  the  horizontal  line  length  in  the  pop¬ 
up  window,  the  prompt  is  truncated.  Horizontal  scrolling  is  not  permitted  in 
a  pop-up  window. 

You  must  define  at  least  one  bar  for  a  pop-up  window;  otherwise,  the  pop-up 
window  is  empty  and  cannot  be  activated. 

The  MESSAGE  expression  is  displayed  centered  on  the  last  line  of  the  screen 
outside  the  pop-up  window.  The  DEFINE  BAR  message  overwrites  any  mes¬ 
sage  text  you  have  written  with  the  DEFINE  POPUP  command.  The  message 
is  limited  to  79  characters;  all  excess  characters  are  truncated.  The  message 
is  tied  to  the  bar  prompt  it  is  defined  with:  it  appears  at  the  bottom  of  the 
screen  when  the  cursor  in  the  pop-up  window  is  on  the  bar  prompt  that  was 
defined  in  the  same  DEFINE  BAR  command. 

Each  bar  prompt  can  have  its  own  message  line  of  79  characters  or  less. 
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Use  the  SKIP  option  to  display  the  desired  BAR,  but  not  allow  its  selection. 
Use  the  SKIP  FOR  option  to  display  the  BAR  and  allow  its  selection  only 
when  the  FOR  condition  is  true. 


Example 

The  following  five  lines  define  menu  choices  for  the  View_pop  pop-up 
menu: 

.  DEFINE  PCRP  Viauxp  from  2, 10 
.  DEFINE  BAR  1  OF  Viauxp  PR&FT  "Add  new  record' 

.  DEFItE  BAR  2  OF  Viauxp  PRCFPT  ' Edit0 
.  DEFINE  BW  J  OF  Viauxp  FRCFPT  REFUCATEC W  9GP 
.  DEFItE  BAR  4  OF  Viauxp  FRCTPT  "Deletd  3GP  FOR  "Medit  cniy 

BAR  3  displays  a  horizontal  line  to  separate  the  Delete  choice  from  the  Add 
and  Edit  choices.  The  SKIP  option  is  included  to  avoid  selecting  the  separa¬ 
tor  line.  A  logical  memory  variable  called  Medit  can  be  defined  to  make  the 
Delete  option  display  only  while  Medit  evaluates  to  a  logical  true  (.T.).  The 
selection  bar  cannot  be  placed  on  bar  4  while  Medit  remains  true,  but  can 
be  selected  when  Medit  evaluates  to  a  logical  false  (.F.). 


See  Also 

ACTIVATE  POPUP,  BAR(),  DEACTIVATE  POPUP,  DEFINE  POPUpTIoN 
SELECTION  POPUP,  POPUPQ,  PROMPTQ,  SHOW  POPUP  1 — 
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DEFINE  BOX 


The  DEFINE  BOX  command  defines  a  box 
text. 


printed  around  lines  of 


Syntax 

DEFINE  BOX  FROM  <  print  column  >  TO  <  print  column  > 

HEIGHT  <  exp  >  [AT  LINE  <  print  lino  ]  [SINGLE/ DOUBLE 
/<  border  definition  string  >  ] 


Usage 

Use  this  command  to  define  a  box  around  report  text  for  enhanced  appear¬ 
ance.  This  command  is  valid  only  for  printed  output. 

This  command  defines  the  beginning  column  on  the  left  and  last  column  on 
the  right,  the  beginning  line  for  the  top  of  the  box,  and  the  height  for  the 
box.  If  the  beginning  coordinates  are  less  than  the  current  coordinates,  they 
are  ignored  and  the  box  begins  at  the  current  line.  Also,  if  no  AT  LINE  is 
specified,  the  box  begins  at  the  current  line. 

The  border  definition  string  follows  the  same  rules  as  the  SET  BORDER 
command.  You  may  specify  a  list  of  character  codes  for  the  border  string,  as 
described  in  SET  BORDER.  The  default  border  is  a  single  line.  The  PANEL 
selection  of  SET  BORDER  is  not  supported. 


Example 

See  the  SET  BORDER  command. 


See  Also 

SET  BORDER 

Chapter  1,  “Essentials,”  describes  how  to  control  printer  output  with  system 
memory  variables. 
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DEFINE  MENU 


Use  DEFINE  MENU  in  conjunction  with  the  DEFINE  PAD  command  to 
define  a  menu. 


Syntax 

DEFINE  MENU  <  menu  name>  [MESSAGE  <  expC>  ] 

Usage 

This  command  is  the  first  step  in  creating  a  bar  menu;  by  itself  it  does  not 
create  a  bar  menu.  This  command  can  only  assign  a  name  to  a  bar  menu 
and  associate  an  optional  message  with  the  menu  name. 

Use  this  bar  menu  name  with  the  DEFINE  PAD  command  to  define  the  menu 
pads  and  their  messages. 

The  optional  MESSAGE  text  field  appears  centered  at  the  bottom  of  the 
screen.  The  message  is  limited  to  79  characters. 

Each  menu  pad  may  have  its  own  message,  or  one  message  may  be  used 
with  all  bar  menu  options.  If  a  PAD  is  assigned  a  message,  the  message  speci¬ 
fied  with  the  DEFINE  MENU  command  is  overwritten. 


Example 

„  DEFI/€  fmj  flbin 

See  Also 

DEFINE  PAD,  MENUQ,  ON  PAD,  ON  SELECTION  PAD,  PAD  () 
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DEFINE  PAD 


Use  the  DEFINE  PAD  command  to  define  a  single  pad  in  a  bar  menu.  To 
define  more  than  one  pad  in  a  menu,  repeat  the  command  with  the  same 
menu  name  until  all  the  pads  are  defined. 


Syntax 

DEFINE  PAD  <  pad  name>  OF  <  menu  name>  PROMPT  <  expC> 

[AT  <  row  >  ,<  col>  ]  [MESSAGE  <  expC>  ] 

Usage 

Use  this  command  to  define  each  pad  for  a  given  bar  menu.  The  pad  name 
follows  the  naming  rules  for  field  and  alias  names.  If  you  use  an  existing  pad 
name  to  define  a  different  pad,  the  earlier  pad  is  overwritten. 

The  <  menu  name>  option  must  be  previously  defined  with  the  DEFINE 
MENU  command. 

The  PROMPT  field  is  the  text  displayed  inside  the  menu  option.  The  program 
adds  a  blank  space  to  each  side  of  the  prompt  message  before  displaying  it. 

Menu  prompts  can  be  positioned  anywhere  on  the  screen.  The  optional 
screen  coordinates  define  the  beginning  point  for  the  prompt  text.  If  you  use 
the  same  x  coordinate  for  consecutive  DEFINE  PAD  commands,  the  result  is 
a  vertical  menu  bar. 

If  you  do  not  specify  coordinates,  the  program  places  the  first  prompt  at  the 
upper  left  corner  of  the  screen.  It  places  each  subsequent  prompt  on  the 
same  line,  one  space  after  the  end  of  the  previous  prompt.  SETjSCORE- 
BOARD  OFF  to  prevent  the  SCOREBOARD  information  from  writing  over 
menu  PADS  on  line  one  of  the  display. 

To  navigate  the  prompts,  use  the  -*  and  *-  keys. 

The  MESSAGE  option  defines  a  message  and  associates  it  with  the  PAD.  The 
message  line  can  be  up  to  79  characters  long;  any  excess  characters  are  trun 
cated.  The  message  appears  centered  at  the  bottom  of  the  screen  when  the 
cursor  is  on  the  pad  associated  with  it.  The  message  text  overrides  any  other 
message  defined  with  the  DEFINE  MENU  command. 

The  total  number  of  pads  you  can  define  is  limited  only  by  the  available 
memory. 
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DEFINE  PAD 


Example 

First,  use  DEFINE  MENU  and  create  a  menu  called  Main.  Then,  define  four 
choices  for  the  Main  bar  menu. 


.  DEFUEFBUmin 

.  DEFHE  PAD  Vieu  OF  min  Pf&PT  ’AH/Edir  AT 2 A 
.  DEFUC  PAD  Goto  OF  min  PKWT  ' Goto/Searcff  AT  2,16 
.  DEFIFE  PAD  Print  OF  min  PRCFPT  ’Print’  AT  2^0 
.  DEFIFE  FAD  Exit  OF  min  PfVFPT  ’ Exit f  AT  2^8 


When  the  cursor  is  placed  on  any  pad  other  than  Exit,  an  appropriate  pop-up 
menu  is  displayed.  The  pop-up  menus  display  as  a  result  of  ON  PAD  com¬ 
mands  found  after  the  DEFINE  PAD  commands  associated  with  them. 


See  Also 

DEFINE  MENU,  ON  PAD,  ON  SELECTION  PAD,  PAD  (),  SET  SCOREBOARD 


LANGUAGE  REFERENCE 
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DEFINE  POPUP 


A  pop-up  menu  is  a  screen  window  containing  special  fields,  messages  and  a 
border.  The  DEFINE  POPUP  command  defines  a  pop-up  window’s  name, 
location,  border,  prompts,  and  message  line. 

Syntax 

DEFINE  POPUP  <  popup  name  >  FROM  <  rowl  >  <  coll  > 

[TO  <  row 2  >  <  col2  >  ]  [PROMPT  HELD  <  field  name> 

/PROMPT  FILES  [LIKE  <  skeleton  >  ]/ PROMPT  STRUCTURE] 
[MESSAGE  <  expC>  ] 


Usage 

The  DEFINE  POPUP  command  arguments  are  as  follows: 

Pop-up  menu  names  follow  the  same  naming  rules  as  the  alias  and  field 
names.  You  must  assign  a  name  to  the  pop-up  menu  so  that  you  can  call  the 
pop-up  menu  to  the  screen  after  you  define  it. 

The  FROM  and  TO  coordinates  define  the  top  left  and  the  bottom  right  cor¬ 
ners  of  the  pop-up  window.  This  window  covers  up  any  other  text  fields  that 
are  displayed  on  the  screen,  including  the  status  line.  Because  only  one 
popup  can  be  active,  several  popups  may  be  defined  at  the  same  screen  coor¬ 
dinates.  Deactivated  popups  are  erased  from  the  screen. 

The  TO  coordinates  are  optional;  if  you  omit  them,  dBASE  IV  defines  the 
window  to  be  long  enough  to  accommodate  the  longest  prompt  within  the 
limits  of  the  screen.  The  screen  limits  a  pop-up  window  to  the  last  column 
(79)  and  the  line  above  the  status  bar  (22). 

If  you  use  the  TO  coordinates,  prompts  that  are  too  long  to  fit  in  the  pop-up 
window  are  truncated  to  fit.  If  all  the  prompts  will  not  fit  in  the  pop-up  win¬ 
dow,  they  scroll  vertically  within  the  pop-up  menu  window  as  you  move  the 
cursor. 

There  are  three  forms  of  the  PROMPT  option:  PROMPT  FIELD,  PROMPT 
FILES,  and  PROMPT  STRUCTURE.  If  you  use  any  of  the  three  when  you 
define  a  pop-up  menu,  then  you  cannot  later  use  the  DEFINE  BAR  command 
with  that  pop-up  menu  name. 

The  PROMPT  FIELD  option  displays  the  contents  of  the  named  field  for  each 
record  of  the  database  file  in  the  pop-up  window.  You  cannot  use  a  memo 
field  in  the  PROMPT  FIELD  option.  You  may,  however,  precede  a  field  name 
with  an  alias. 

If  you  enter  the  FILES  option,  the  CATALOG  filenames  are  displayed  in  the 
pop-up  window.  Specifying  the  LIKE  <  skeleton  >  parameter  restricts  the 
files  displayed  in  the  pop-up  window  to  those  that  match  the  skeleton.  With¬ 
out  the  LIKE  <  skeleton  >  filter,  all  files  in  the  active  catalog  are  displayed. 
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If  you  use  the  STRUCTURE  option,  you  see  the  defined  fields  in  the  pop-up 
window  Defined  fields  consist  of  all  the  fields  in  the  active  database  file,  or 
the  fields  in  the  SET  FIELDS  list  if  the  SET  FIELDS  command  is  ON. 

The  MESSAGE  expression  is  displayed  centered  in  the  bottom  line  of  the 
screen,  outside  the  pop-up  window.  The  maximum  message  is  79  characters 
long;  any  excess  characters  are  truncated.  The  message  line  is  the  only  way 
to  include  a  message  text  for  the  FIELD,  FILES,  or  STRUCTURE  options. 


Example 

The  four  pop-up  menus  used  in  the  sample  file  are  defined  with  these 
com  mands: 


.  DEFINE  PORJP  Viacpop  FROM  3^3  TO  7,20 
.  DEFUE  PCRP  Viaarp  FROM  3,15  TO  9^3 
.  DEFUE  PCFIP  VioLpep  FROM  3^9  TO  5^9 
.  DEFUE  PORP  Viaurp  FROM  3^5  TO  4>5/ 


These  pop-up  menus  are  given  coordinates  that  position  them  directly  below 
their  corresponding  pads  on  the  Main  bar  menu. 


See  Also 

ACTIVATE  POPUP,  BAR(),  DEFINE  BAR,  ON  SELECTION  POPUP,  POPUPQ, 
PROMPTQ 


LANGUAGE  REFERENCE 
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DEFINE  WINDOW 


The  DEFINE  WINDOW  command  defines  windows,  borders,  and  screen 
colors  for  windows. 

Syntax 

DEFINE  WINDOW  <  window  name>  FROM  <  rowl>  ,<  coll  >2 TO 
<  row2>  ,<  col2>  [DOUBLE/ PANEL/ NONE/^:  border  definition 
string  >  ]  [COLOR  [<  standard  >  ]  [,<  enhanced  >  ]  [,<  frame  >  ]] 


Usage 


Use  this  command  to  define  the  screen  coordinates  and  the  display  attributes 
of  a  window  and  its  borders.  The  FROM  coordinates  determine  the  upper 
left  row  and  column  for  the  window,  and  the  TO  coordinates  determine  the 
bottom  right  row  and  column. 

The  border  default  is  a  single  line  box.  Alternately,  you  can  define  a  double 
line  box,  dejne  an  inverse  video  panel,  or  suppress  borders  altogether.  Bor¬ 
der  definition  strings  use  ASCII  codes,  as  explained  for  the  SET  BORDER 
command. 

If  you  change  the  SET  BORDER  parameters,  the  window  retains  the  border 
format  that  was  in  effect  when  it  was  defined.  If  no  color  is  specified,  screen 
attributes  follow  the  colors  that  were  in  effect  on  the  screen  when  the  win¬ 
dow  was  defined. 

Avoid  using  ASCII  codes  7,  8,  10,  12,  13,  27,  and  127  in  border  definitions. 
These  codes  display  on  the  screen,  but  cause  problems  with  print  drivers,  or 
if  you  use  the  Shift-PrtSc  key  to  print  out  the  screen  contents. 

You  may  store  up  to  20  window  definitions  in  memory  at  one  time. 

Example 

This  example  opens  a  small  window  at  the  upper  right  corner  of  the  screen. 
The  sample  border  definition  string  uses  the  asterisk  character  (ASCII  42)  for 
the  borders,  and  the  number  1  (ASCII  49)  at  the  upper  left  corner  as  an 
optional  window  number.  It  uses  a  plus  sign  (ASCII  43)  for  the  other  three. 


TaCTivate  UIMCW  Wl 


See  Also 

ACTIVATE  WINDOW,  DEACTIVATE  WINDOW,  RESTORE  WINDO  ^E 
WINDOW,  SET  BORDER  TO,  SET  COLOR 
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DELETE 


DELETE  marks  records  in  the  active  database  file  for  deletion. 

Syntax 

DELETE  [<  scope  >  ]  [FOR  <  condition  >  ]  [WHILE  <  condition  >  ] 


Defaults 

Unless  otherwise  specified  by  the  scope  or  a  FOR  or  WHILE  clause,  only  the 
current  record  is  marked  for  deletion. 

Usage 

This  command  does  not  remove  records  from  the  database  file.  DELETE 
marks  records  for  deletion,  and  PACK  removes  them  from  the  database  file. 
You  can  unmark  records  already  marked  for  deletion  with  RECALL. 

When  you  use  DISPLAY  and  LIST  to  call  up  records,  those  marked  for  dele¬ 
tion  are  indicated  by  an  asterisk  (*)  in  the  first  position  of  the  record. 

With  full-screen  commands  such  as  BROWSE  or  EDIT,  records  marked  for 
deletion  are  indicated  by  Del  on  the  status  bar.  In  this  mode,  Ctrl-U  both 
deletes  and  reinstates  records. 


Record  Pointer 


DELETE  does  not  reposition  the  record  pointer,  unless  you  give  the  scope,  a 
FOR  clause,  or  a  WHILE  clause.  Therefore,  if  you’re  at  the  end  of  the  file,  as 
after  LIST  or  DISPLAY  ALL,  issuing  DELETE  has  no  effect. 


Example 

To  mark  record  6  for  deletion: 


DELETE  RECORD  6 
1  record  deleted 
RECALL  ALL 
1  record  recalled 


See  Also 

DELETEDQ,  PACK,  RECALL,  SET  DELETED,  ZAP 


LANGUAGE  REFERENCE 
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DELETE  TAG 


DELETE  TAG  deletes  the  indicated  tags  from  a  multiple  index  (.mdx)  file  if 
tag  names  are  specified,  and  closes  index  (.ndx)  files  if  index  file  names  are 
specified. 


Syntax 

DELETE  TAG  <  tag  name  1  >  [OF  <  .mdx  filename  >  ]/  <  ndx  filename  1  > 
[,<  tag  name  2>  [OF  <  .mdx  filename  >  ]/ <  .ndx  filename  2>  ...] 


Usage 

Multiple  index  (.mdx)  files  may  contain  up  to  47  tags,  each  of  which  imposes 
an  index  order  on  the  database  file. 

A  production  .mdx  file  is  an  .mdx  file  that  is  opened  whenever  the  database 
file  is  USEd.  Production  .mdx  files  have  the  same  name  as  their  associated 
database  files,  but  with  an  .mdx  file  extension.  The  database  file  header  con¬ 
tains  an  indication  that  there  is  an  associated  production  .mdx  file. 

If  you  no  longer  need  one  or  more  of  the  tag  indexes  in  any  active  multiple 
index  file,  you  can  remove  it  with  the  DELETE  TAG  command.  Deleting  a  tag 
index  permanently  removes  it  from  the  multiple  index  file,  and  restores 
space  to  the  file.  DELETE  TAG  opens  a  slot  for  a  new  tag  index  to  be  created 
in  the  .mdx  file. 

The  multiple  index  file  containing  the  tag  must  be  open  for  DELETE  TAG  to 
work,  but  the  tag  that  is  being  deleted  does  not  have  to  be  the  controlling 
index. 

If  you  delete  all  tags  in  a  multiple  index  file,  the  .mdx  file  is  also  deleted.  If 
you  delete  the  production  mdx  file  by  removing  all  its  tags,  the  database  file 
header  is  updated  to  indicate  that  no  production  .mdx  file  is  associated  with 
this  database  file.  If  a  catalog  is  open,  it  is  updated  to  reflect  the  changes. 

Using  the  OF  clause,  you  may  specify  the  .mdx  file  that  contains  the  tag.  If 
the  tag  is  contained  in  an  .mdx  file  other  than  the  production  .mdx  file,  or  if 
two  open  .mdx  files  contain  the  same  tag  name,  you  should  include  the  OF 
clause  in  the  command  to  indicate  the  correct  tag  for  deletion.  If  a  tag  can¬ 
not  be  found,  the  error  message  TAG  not  found  appears. 

DELETE  TAG  operates  differently  when  given  index  (.ndx)  filenames.  The 
index  file  is  closed,  not  deleted  from  the  disk.  The  result  is  similar  to  SET 
INDEX,  although  the  operation  is  slightly  different.  The  DELETE  TAG  syntax 
provides  a  convenient  way  to  close  certain  .ndx  files,  when  several  are  open, 
without  closing  and  reopening  the  others.  SET  INDEX,  however,  closes  all 
.ndx  files  and  then  reopens  any  files  that  should  not  be  closed. 
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DELETE  TAG 


Special  Cases 

In  a  network  environment,  the  database  file  must  be  in  exclusive  use  before 
you  can  issue  DELETE  TAG.  If  the  database  file  is  not  in  exclusive  use,  the 

error  message  Exclusive  use  of  database  is  required  appears. 


Example 

To  delete  the  Client  tag  from  the  Client  production  .mdx  file: 

.  DELETE  TAG  CL  ient  OF  Client 

See  Also 

COPY  INDEX,  COPY  TAG,  INDEX,  MDX(),  NDX(),  ORDER(),  SET  INDEX, 
SET  ORDER,  TAG(),  USE 


LANGUAGE  REFERENCE 
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DIR 


DIR  displays  directory  information  similar  to  that  displayed  by  the  DOS  DIR 
command. 


Syntax 

DIRECTORY/ DIR  [[ON]  <  drive>  :]  [[LIKE]  <  path>  ]  [<  skeleton  >  ] 


Defaults 

If  you  do  not  specify  a  filename  or  skeleton,  the  DIR  command  provides 
directory  information  only  on  database  files.  If  you  do  not  specify  a  path  or 
drive,  the  DIR  command  provides  information  only  on  the  current  drive  and 
directory. 


Usage 

For  database  files,  DIR  displays  the  files,  number  of  records,  date  of  last 
update,  file  size  (in  bytes),  total  number  of  files  displayed,  total  number  of 
bytes  for  the  displayed  files,  and  the  total  number  of  bytes  remaining  on  disk. 
If  you  specify  any  file  type  other  than  .dbf  in  the  command,  DIR  displays 
only  the  filenames. 

The  directory  may  not  reflect  changes  to  newly  changed  files  until  after  the 
file  is  closed,  unless  SET  AUTOSAVE  is  ON. 


Examples 

To  display  the  database  files  in  the  current  directory: 

.  DIR 

To  display  all  filenames  in  the  current  directory: 

.  DIR  *.* 

To  display  all  compiled  program  files  in  the  \SALES  subdirectory: 
.  DIR  \SALES\*.abo 
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DIR 


To  display  filenames  that  are  five  characters  long  where  D  is  the  third 
character: 

.  DIR  ??D??.* 

To  display  all  .dbf  files  in  another  directory  called  Sales: 

.  DIR  \S*£S\ 

See  Also 

DEFINE  POPUP,  FILE(),  UST/ DISPLAY  FILES,  SET  AUTOSAVE, 

SET  CATALOG 


LANGUAGE  REFERENCE 
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DISPLAY  Commands 


The  following  DISPLAY  commands  are  similar  to  their  LIST  counterparts.  If 
you  use  the  DISPLAY  form  of  the  command,  only  one  screen  of  information 
is  presented  at  a  time,  and  a  prompt  appears  asking  you  to  press  a  key  to  see 
the  next  screen. 

Both  the  DISPLAY  and  LIST  forms  allow  you  to  send  output  to  a  disk  file  by 
using  the  TO  <  filename >  option. 

Please  refer  to  the  following  LIST  commands  for  a  discussion  of  both  the 
LIST  and  DISPLAY  forms: 

LIST/ DISPLAY 
LIST/DISPLAY  FILES 
LIST/ DISPLAY  HISTORY 
LIST/ DISPLAY  MEMORY 
LIST/ DISPLAY  STATUS 
LIST/ DISPLAY  STRUCTURE 
LIST/ DISPLAY  USERS 
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DO  executes  a  dBASE  command  file  or  procedure.  If  the  command  file  or 
procedure  file  has  not  been  COMPILEd,  it  is  first  parsed  and  saved  as  an 
object  file  with  a  dbo  extension;  then,  the  .dbo  file  is  executed. 

DO  may  also  pass  parameters  to  the  named  program. 


Syntax 

DO  <  program  filename  >  /<  procedure  name> 

[WITH  <  parameter  list >  ] 

Defaults 

Unless  the  file  is  on  the  default  drive  or  a  path  is  set,  the  filename  must 
include  the  drive  designator.  The  filename  must  also  include  a  path,  if  the 
file  is  not  on  the  default  directory  or  on  a  path  set  with  the  SET  PAHI 
command. 

You  should  not,  however,  precede  the  names  of  procedures  within  a  proce¬ 
dure  file  with  a  drive  designator  or  path.  The  drive  designator  and  path  for 
procedure  files  should  be  stated  in  the  SET  PROCEDURE  command. 

The  following  search  order  is  used  when  you  issue  a  DO  command. 

1.  DO  searches  for  a  procedure  in  the  current  .dbo  file,  if  one  is  being 
executed. 

2.  DO  searches  for  a  procedure  in  a  procedure  file,  if  a  SET  PROCEDURE 
command  activated  one. 

3.  DO  searches  for  a  procedure  in  other  open  .dbo  files. 

4.  DO  searches  for  a  .dbo  file. 

5.  DO  searches  for  a  .prg  file,  compiles  it,  and  then  executes  the  resultant 
.dbo  file. 

6.  DO  searches  for  a  .prs  file,  compiles  it,  and  then  executes  the  resulting 
.dbo  file. 

DO  determines  whether  the  file  is  an  object  or  source  file,  and  executes  the 
file  if  it  is  an  object  (.dbo)  file,  or  compiles  and  executes  the  file  if  it  is  a 
source  (  prg  or  .prs)  file. 


LANGUAGE  REFERENCE 
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DO 


Usage 

dBASE  IV  supports  the  concept  of  procedures  within  any  program  file  by 
maintaining  a  procedure  list  at  the  beginning  of  every  object  (.dbo)  file.  If  a 
source  file  starts  with  a  command  other  than  PROCEDURE  or  FUNCTION, 
the  code  is  compiled  as  a  procedure  and  added  to  the  procedure  list  in  the 
object  file  with  the  same  name  as  the  source  file.  Atypical  .prg  file  such  as: 

*  Main.prg 
?  "MAIN* 

RETIRJ 


is  compiled  into  a  .dbo  file  containing  one  procedure,  Main.  When  you  enter 
DO  MAIN,  this  name  is  used  to  locate  the  .dbo  file,  and  then  used  to  locate 
the  procedure  within  the  .dbo  file. 

A  source  file  can  include  more  than  one  procedure,  such  as: 

*  ftein.prg 
?  "MAIN' 

DO  Scfcb 
RETIRJ 


PRDCEDtRE  Si±b 
?  ''  SLEET 
RETIRJ 

Note  that  only  comands  found  at  the  beginning  of  a  file  are  given  the  default 
procedure  name.  Commands  between  RETURN  and  PROCEDURE  cause  a 
compile-time  warning.  Yo  i  may  want  to  keep  this  code  in  the  program  file, 
but  DO  will  not  execute  these  commands. 


Any  procedure  found  in  an  active  .dbo  file  is  available  to  the  DO  command. 
If  Adbo  calls  B.dbo  calls  C.dbo,  all  the  procedures  defined  within  A  B, 
and  C  are  available  to  any  procedure  in  C.  dBASE  IV  still  supports  SET 
PROCEDURE  from  dBASE  III  and  dBASE  III  PLUS,  although  this  command 
is  only  required  to  gain  access  to  procedures  in  a  file  not  activated  by  DO 
<  filename  >  . 

Each  source  file  or  object  file  that  DO  executes  opens  a  file  handle.  Each 
procedure  within  a  file,  however,  does  not  open  a  file  handle.  You  may  have 
a  maximum  of  32  active  .dbo  files.  A  .dbo  file  is  active  if  you  open  it  with 
SET  PROCEDURE,  or  if  a  RETURN  can  pass  control  back  to  it. 
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The  total  number  of  open  file  handles  for  all  files,  including  database  files, 
index  files,  format  files,  and  command  files,  is  determined  by  the  FILES 
setting  in  the  Config.sys  file.  In  a  DOS  environment  five  file  handles  are 
reserved;  therefore  you  can  have  up  to  94  files  open  if  you  set  FILES  -  99, 
which  is  the  maximum  setting  in  Config.sys. 

When  the  program  called  by  DO  is  complete,  control  returns  to  the  calling 
program  (or  to  the  dot  prompt  or  Control  Center  if  the  DO  command  was 
issued  from  either  of  those  points). 

Memory  variables  and  arrays  created  in  the  called  program  must  be  declared 
PUBLIC  if  they  are  to  be  used  after  the  called  program  terminates.  All 
PRIVATE  memory  variables  and  arrays  created  within  the  program  are 
released  once  the  program  terminates. 

Because  DO  first  searches  for  .dbo  files,  you  should  not  change  the  file 
extension  once  a  program  has  been  compiled.  All  programs  should  have 
unique  names,  because  once  compiled  they  can  no  longer  be  distinguished 
by  their  file  extensions. 

If  SET  DEVELOPMENT  is  ON,  DO  compares  the  time  and  date  stamp  of  a 
.prg  file  with  the  time  and  date  stamp  of  its  associated  .dbo  file.  If  the  .dbo 
file  is  older  than  the  .prg  file,  DO  recompiles  the  .prg  file  before  executing  it. 

The  dBASE  IV  program  editor,  which  can  be  accessed  from  MODIFY 
COMMAND  or  the  Control  Center,  will  delete  an  old  .dbo  file  when  a  .prg 
file  is  modified,  and  then  recompile  the  new  .prg  file  (generating  a  new  dbo 
file)  when  you  save  it.  As  other  text  editors  will  not  delete  the  old  .dbo  file 
and  recompile  a  new  one,  SET  DEVELOPMENT  allows  you  to  verify  that  DO 
does  not  execute  an  outdated  .dbo  file. 


Options 

The  WITH  option  allows  parameters  to  be  passed  to  a  subroutine.  The 
parameter  list  can  contain  any  valid  dBASE  expression,  and  you  may  pass  up 
to  50  parameters.  Field  names  take  precedence  over  memory  variables,  so  to 
specify  a  memory  variable  as  a  parameter  rather  than  a  field  with  the  same 
name,  precede  the  memory  variable  name  with  M->  . 

Tips 

Avoid  DOing  a  command  file  recursively.  A  comm  and  file  may  contain  a  DO 
command  that  executes  itself  over  again,  or  the  command  file  may  DO  a  sub¬ 
routine,  and  that  subroutine  may  DO  the  original  command  file.  Both  are 
recursive  calls,  and  both  cases  will  open  two  file  handles  for  the  same  com¬ 
mand  file.  The  error  messages  Too  many  files  are  open  or  DOs  nested  too 
deep  may  eventually  result.  dBASE  IV  will  allow  up  to  32  nested  DOs. 
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DO 


A  subroutine  or  procedure  should  return  control  to  the  calling  program  with 
a  RETURN  command,  not  with  a  DO  command.  If  a  command  file  needs  to 
execute  its  own  commands  again,  the  commands  should  be  contained  in  a 
DO  WHILE  loop.  The  command  file  should  not  DO  itself  again. 


Special  Case 

If  the  input  file  has  a  .upd  extension,  DO  generates  a  .upo  file  and  executes 
the  update  query. 


Examples 

The  following  program  file,  Areacalc.prg,  calculates  the  area  of  a  rectangle 
based  on  the  formula  area  =  length  *  width: 

*  Pregram  name:  Areacalc.prg 
PARAf€7ERS  MJ.ength,  M_width,  floras 
M_area  =  MJength  *  M_width 
RETUW 

*  ECP:  Areacalc.prg 

To  execute  the  program  file  Areacalc,  pass  the  values  4  and  6  to  the  memory 
variables  M_ length  and  M_ width  respectively,  and  return  the  correct  value 
to  the  memory  variable  called  M_ result: 

.  HsesjLt  =  0 

O.CDj 

.  DO  Areacalc  UI7H  6,  4,  Hsesult 
Corpiling  line  5 
24.00 
.  ?  tLresult 
24.00 


See  Also 

CANCEL,  COMPILE,  CREATE/ MODIFY  QUERY/VIEW,  DEBUG,  FUNCTION, 
MODIFY  COMMAND,  PARAMETERS,  PRIVATE,  PROCEDURE,  PUBLIC, 
RETURN,  SET  DEBUG,  SET  DEVELOPMENT,  SET  ECHO,  SET 
PROCEDURE,  SET  TRAP 
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DO  CASE 


DO  CASE  is  a  structured  programming  command  that  selects  only  one 
course  of  action  from  a  set  of  alternatives. 


Syntax 

DO  CASE 

_CASE  <  condition  > 
7<  cojmmands > 
[CASE  <  condition  > 
~<  coin  mands  >  ] 
[OTHERWISE 
<  co)mmands>  ] 
ENDCASE 


Usage 

ENDCASE  terminates  the  DO  CASE  structure.  Command  pairs  such  as  DO 
CASE... ENDCASE,  IF...ENDIF,  and  DO  WHILE. .. ENDDO  must  be  properly 
nested  within  DO  CASE.  Nested  DO  CASEs  are  permitted. 

CASE  <  condition  >  sets  up  a  condition,  or  logical  expression  such  as 
A  -  ^  or  Numvar  <  11,  for  evaluation.  When  the  condition  evaluates  to  a 
logical  true  (.T.),  all  subsequent  commands  are  carried  out  until  any  one  of 
the  following  commands  is  reached:  another  CASE,  OTHERWISE,  or 
ENDCASE. 

After  one  true  CASE  is  found  and  its  associated  commands  processed,  no  fur¬ 
ther  CASE  statements  are  evaluated,  and  dBASE  IV  skips  immediately  to  the 
first  command  after  ENDCASE.  If  no  CASE  statements  evaluate  true,  and 
there  is  no  OTHERWISE  statement,  the  program  processes  the  first  com¬ 
mand  following  ENDCASE.  OTHERWISE  causes  the  program  to  take  an 
alternative  path  of  action  when  all  CASE  statements  evaluate  to  false  (.F.). 


Tips 


Only  one  of  the  possible  cases  is  acted  upon,  even  if  several  apply.  In  situa¬ 
tions  where  only  the  first  true  instance  is  to  be  processed,  the  DO  CASE 
command  is  preferable  to  the  IF  command. 

The  CASE  construct  is  often  used  when  there  are  a  small  number  of  excep¬ 
tions  to  a  condition.  The  CASE  <  condition  >  statements  can  represent  the 
exceptions,  and  the  OTHERWISE  statement  the  more  common  situation. 
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DO  CASE 


Example 

Compare  this  example  with  the  example  given  for  the  IF  command.  The 
following  CASE  construct  determines  the  magnitude  of  a  variable  and  dis¬ 
plays  an  appropriate  message: 


DO  CASE 

CASE  M^alue  >  100 
T^Value  is  ever  100." 

CASE  ^Lvalue  >  10 
I3/alue  is  over  10/ 

CASE  *_vali*  >  1 
33*  lue  is  ewer  1/ 
OTHERWISE 

T*Hhe  value  is  1  or  less/ 
0DCASE 


See  Also 

DO,  DO  WHILE,  IF,  IIF() 
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DO  WHILE  is  a  structured  programming  command  that  allows  command 
statements  between  it  and  its  associated  ENDDO  to  be  repeated  as  long  as 
the  specified  condition  is  true. 

Syntax 

DO  WHILE  <  condition  > 

<  cijm mands > 

[LOOP] 

[EXIT] 

ENDDO 


DO  WHILE  <  condition  >  opens  a  structured  procedure  that  processes  sub¬ 
sequent  commands  only  while  the  condition  evaluates  to  true  (.T.);  for  exam¬ 
ple,  .NOT.  EOF()  .AND.  Mvarl  =  11. 

If  the  condition  evaluates  to  .T.,  all  subsequent  commands  are  carried  out 
until  an  ENDDO,  LOOP,  or  EXIT  is  encountered.  ENDDO  and  LOOP  return 
control  to  the  DO  WHILE  command  for  another  evaluation  of  the  condition. 
EXIT  passes  control  to  the  statement  following  the  ENDDO. 

LOOP  returns  control  to  the  beginning  of  a  DO  WHILE. ..ENDDO  program 
structure.  LOOP  prevents  the  execution  of  the  remaining  commands  in  the 
DO  WHILE  construct. 

EXIT  transfers  control  from  within  a  DO  WHILE. ..ENDDO  loop  to  the  com¬ 
mand  immediately  following  the  ENDDO. 

ENDDO  must  terminate  a  DO  WHILE  structure.  The  space  following  the 
ENDDO  on  the  command  line  may  be  used  for  comments;  the  comment 
indicator,  &&,  is  not  needed. 

Any  structured  commands  within  a  DO  WHILE.. .ENDDO  structure  must  be 
properly  nested.  Nested  DO  WHILEs  are  permitted. 

If  the  condition  evaluates  to  a  logical  false  (  F.),  dBASE  IV  skips  all  com¬ 
mands  between  DO  WHILE  and  ENDDO  and  goes  to  the  command  following 
ENDDO. 

Programming  Notes 

You  can  use  macros  in  the  conditional  portion  of  a  DO  WHILE  loop  only  if 
the  value  of  the  variable  in  the  macro  does  not  change,  because  the  DO 
WHILE  statement  is  parsed  only  the  first  time  through  the  loop.  After  the 
first  parsing,  the  DO  WHILE  statement  is  executed  from  memory. 
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DO  WHILE 


Macro  substitution  must  also  be  within  the  lowest  nested  level  of  a  program 
and  within  the  lowest  nested  DO  WHILE  loop.  If  the  DO  WHILE  loop  that 
contains  the  macro  has  a  nested  DO  WHILE  loop  or  DO  <  program 
filename  >  within  it,  the  condition  of  the  loop  will  always  evaluate  to  .T. 
after  the  first  evaluation,  and  the  program  will  remain  in  an  endless  loop. 

Examples 

The  first  example  shows  how  to  correctly  use  a  macro  in  the  conditional  por¬ 
tion  of  a  DO  WHILE  loop  executing  in  a  dBASE  program  file: 

*  This  is  an  exanple  of  the  correct  «y  to  use  a  macro  in  a  DO  VHILE  statement. 

* 

LEE  Transact  CRD6R  Client_id 
Condition  =  CLPPERCCLiantJd)  = "  CCECDT  ] 

find  comm 

DO  UHILE  aCcndition.  .AD.  .NOT.  EOFO 

*  The  value  of  Condition  never  charges  within  the  Loop. 

?  OrderJd/  DateJrans,  TotaLbill 
SKIP 
EfDOO 

CLOSE  DATABASE 

The  next  program  file  example  illustrates  the  correct  use  of  the  EXIT  and 
LOOP  options.  The  program  lets  you  view  five  records  from  the  Stock  data¬ 
base  file,  and  then  decide  whether  you  want  to  see  the  next  five  or  back  up 
and  see  the  previous  five. 

*  Program  name:  Partial.prg 
I  USE  Stock 
LjJO  UHILE  .NOT.  EOFO 
CLEAR 

LIST  fEXT  5  OrderJd,  Part_name,  Item_cost 


CASE  Mstop  S&&P 


SKIP  -9 
OTVERWISE 
3CIP 
BDCASE 
0DOO 

*  ECP:  Ffertial.prg 


See  Also 

DO,  DO  CASE,  IF,  RETURN,  SCAN 
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EDIT 


EDIT  is  a  full-screen  command  you  use  to  display  or  change  the  contents  of 
a  record  in  the  active  database  file  or  view. 


Syntax 


)]T  [NOINIT]  [NOFOLLOW]  [NOAPPEND]  [NOMENU]  [NOEDIT] 
■jELETE]  [NOCLEAR]  [<  record  number  >  ]  [FIELDS^:  field  1  ist  >  ] 
dcope>  ]  [FOR  <  condition  >  ]  [WHILE  <  condition  >] 


Defaults 

If  you  use  EDIT  without  a  scope,  or  with  a  FOR  or  WHILE  clause,  you  can 
move  through  all  records  in  the  database  file. 


Usage 

EDIT  and  CHANGE  are  identical  commands. 

You  can  change  from  EDIT  to  BROWSE  by  pressing  the  F2  Data  key.  EDIT 
displays  data  according  to  the  definitions  set  in  a  format  (.fmt)  file  if  one  is 
active,  or  in  a  default  vertical  field  arrangement  if  a  format  is  not  active. 
BROWSE  displays  multiple  records  in  a  tabular  format. 

EDIT  uses  the  standard  full-screen  cursor  control  keys.  The  arrow  keys  move 
the  cursor  within  a  record.  PgUp  backs  up  to  the  previous  record.  PgDn 
advances  to  the  next  record.  To  exit  and  save  all  changes,  press  Ctrt-End. 
Press  Esc  to  exit  and  save  changes  to  all  but  the  current  record.  To  EDIT  a 
memo  field,  enter  Ctrl-PgDn  when  the  cursor  is  positioned  on  the  memo 
field  name. 

Unless  you  use  the  NOAPPEND  option,  EDIT  allows  you  to  append  records 
to  a  database  file  if  you  cursor  past  the  last  record  of  the  file.  In  this  way,  it 
works  just  like  the  full-screen  APPEND  command. 

When  called  from  BROWSE,  EDIT  respects  all  the  BROWSE  command  line 
options  except  COMPRESS,  FREEZE,  LOCK,  WIDTH,  and  WINDOW. 
BROWSE  also  respects  all  EDIT  command  line  options. 

Options 

NOINIT  allows  the  command  line  options  that  you  used  with  a  previous 
EDIT  command  to  be  used  in  the  current  EDIT.  NOINIT  instructs  the  EDIT 
command  not  to  initialize  the  EDIT  table,  but  to  use  the  table  from  the  most 
recent  EDIT  instead. 
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EDIT 


NOFOLLOW  applies  only  to  indexed  data.  If  you  specify  NOFOLLOW,  editing 
a  key  field  in  a  record  repositions  the  record  to  its  new  position  in  the  index 
order;  and  the  record  that  then  takes  the  old  record’s  place  becomes  the  cur¬ 
rent  record  on  the  screen.  If  you  do  not  specify  NOFOLLOW,  the  edited 
record  is  repositioned  after  the  key  is  changed;  the  record  following  the 
newly-positioned  record  becomes  the  current  on  the  screen. 

NOAPPEND  prevents  you  from  adding  records  to  the  database  file  during  the 
edit. 

NOMENU  prevents  access  to  the  EDIT  menu  bar. 

NOEDIT  prevents  you  from  changing  any  data  presented  on  screen.  You  can 
add  records,  however,  if  you  cursor  to  the  end  of  the  file,  and  you  can  mark 
records  for  deletion  with  Ctri-U. 

NODELETE  prevents  you  from  deleting  records  during  the  edit  with  the 
Ctri-U  key. 

NOCLEAR  keeps  the  record’s  image  on  the  screen  after  you  exit  the  EDIT. 

<  record  number  >  starts  the  edit  on  the  specified  record,  but  lets  you 
move  to  other  records  in  the  file.  RECORD  <  record  number>  limits  the 
command  to  one  record.  Because  EDIT  RECORD  <  record  number>  limits 
the  edit  to  the  specified  record,  EDIT  RECORD  <  record  number >  and 
EDIT  <  record  number >  are  not  identical. 


Tips 

If  SET  AUTOSAVE  is  OFF,  the  directory  entry  for  the  active  database  file  may 
not  reflect  all  new  records  until  the  file  is  closed.  If  SET  AUTOSAVE  is  ON, 
the  directory  on  disk  is  updated  after  each  new  record  is  added. 


Special  Cases 

In  a  network  environment,  if  you  have  neglected  to  lock  a  record  with 
Ctrt-Oor  LOCK()  before  making  a  change,  dBASE  IV  attempts  to  lock  the 
record  and  any  related  records  as  soon  as  you  press  a  key  that  is  not  a  navi¬ 
gation  key. 


See  Also 

BROWSE,  CHANGE,  CREATE/ MODIFY  QUERY/ VIEW,  MODIFY 
COMMAND,  SET  AUTOSAVE,  SET  DESIGN,  SET  FIELDS,  SET  FORMAT, 
SET  LOCK,  SET  REFRESH,  SET  WINDOW  OF  MEMO 
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EJECT 


EJECT  causes  the  printer  to  advance  the  paper  to  the  top  of  the  next  page. 

Syntax 

EJECT 

Usage 

Unless  you  have  set  the  _padvance  system  variable  to  "LINEFEEDS", 

EJECT  issues  a  form  feed  (ASCII  code  12)  to  the  printer.  If  _padvance  is 
"LINEFEEDS",  EJECT  issues  line  feeds  (ASCII  code  10)  to  position  to  the 
top  of  form . 

For  proper  printer  operation,  you  must  initially  set  the  paper  to  the  top  of 
form.  Refer  to  your  printer  manual  for  instructions. 

EJECT  resets  PROWQ  and  PCOL()  to  zero,  and  increments  the  _pageno 
variable  by  one. 

Tips 

In  a  program  file,  you  may  want  to  verify  the  printer  is  connected  and  on¬ 
line  with  PRINTSTATUS()  before  issuing  an  EJECT. 

See  Also 

???,  ON  PAGE,  PAGENOQ,  PCOLQ,  PRINT,  PRINTSTATUS(),  PROWQ, 

SET  DEVICE,  SET  PRINT 

Chapter  5,  “System  Memory  Variables,”  includes  a  discussion  of  _padvance 
and  _pageno. 
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EJECT  PAGE  advances  the  current  page  in  a  printer  and  stops  at 
the  top  line  of  the  next  page.  Unlike  the  EJECT  command,  which 
only  affects  the  printer,  the  output  of  EJECT  PAGE  goes  to  any 
destination  that  is  currently  available  to  the  ?  command. 

~H3~Syntax 

EJECT  PAGE 

-H3-Usage 

By  itself,  EJECT  PAGE  advances  the  printer  to  the  top  of  the  nex; 
page.  If  you  have  enabled  the  ON  PAGE  handler,  however,  EJECT 
PAGE  will  activate  it  and  the  ON  PAGE  handler  will  control  the 
printer.  The  ON  PAGE  handler  should  include  instructions  for 
advancing  the  paper. 

When  the  EJECT  PAGE  command  is  encountered  in  a  program,  three 
events  take  place: 

~#~1.  The  output  of  formfeeds  or  linefeeds  is  sent  to  all  the 
available  destinations. 

-oo-If  SET  PRINTER  is  ON,  output  goes  to  the  printer.  The  defau] 
is  one  formfeed  that  advances  the  paper  to  the  top  of  the  next 
sheet.  To  issue  linefeeds  (ASCII  code  10)  instead  of  a  formfeed 
(ASCII  code  12) ,  you  need  to  set  the  _padvance  system  variable  t 
~IM~LINEFEEDS~IM~. 

-oo-If  SET  ALTERNATE  is  ON,  output  goes  to  the  end  of  the 
alternate  file.  The  file  receives  carriage  returns  and  linefeeds 
based  on  the  current  values  in  the  _plength  and  _plineno  system 
variables. 

-oo-If  SET  CONSOLE  is  ON,  output  goes  to  the  CRT  display.  The 
display  will  skip  lines  on  the  screen  based  on  the  current  valus 
in  the  _plength  and  _plineno  system  variables. 

-#~2.  The  _pageno  variable  is  incremented. 

- #~3 .  The  _plineno  variable  is  set  to  zero  (0). 

-H3-Tips 

In  program  files,  you  may  want  to  verify  that  the  printer  is 
connected  and  on-line  with  PRINTSTATUS ( )  before  issuing  an  EJECT 
PAGE  command. 

Always  check  your  printer  to  see  that  the  paper  is  correctly 
aligned. 

~H3~See  Also 
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?,  ???,  EJECT,  ON  PAGE,  PAGENO ( ) ,  PRINT,  PRINTSTATUS ( ) ,  SET 
DEVICE,  SET  PRINT 


Chapter  5,  -I-System  Memory  Variables-R-,  includes 
of  _padvance,  _plength,  and  _plineno. 


discussion 
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ERASE 


ERASE  removes  a  file  from  the  disk  directory. 


Syntax 

ERASE  <  filename >  /? 


DELETE  FILE  <  filename >  /? 


17 


Defaults 

The  filename  must  include  the  file  extension.  If  the  file  is  not  on  the  default 
drive,  include  the  drive  designator. 

Usage 

Use  ERASE  ?  to  display  a  menu  of  files. 

You  may  not  delete  an  open  file. 

To  erase  a  file  in  another  directory,  you  must  explicitly  state  the  path  in  the 
filename. 

If  you  ERASE  a  database  file  (.dbf)  that  has  memo  fields,  you  must  separately 
delete  the  .dbt  file  that  contains  the  memo  fields. 

Unlike  the  DOS  ERASE  command,  dBASE  IV  does  not  permit  the  use  of 
wildcard  characters. 

DELETE  FILE  is  the  same  as  ERASE. 

See  Also 

CLOSE,  DELETE,  DELETE  TAG,  FILEQ,  USE 


2-130 


COMMANDS 


PAGE:  131  SESS:  12  Tut  I1«y  10  12:35:12  1  988 
sk2/al  I  jobz/CLS_niBnhBt/GRP_mBnhat/JOB_pian  langref /DIV_lrchap2c 


EXPORT 


EXPORT  copies  the  open  database  file  to  a  file  format  usable  by  PFS:FILE», 
dBASE  II,  Framework  II,  or  RapidFile. 

Syntax 

EXPORT  TO  <  filename  >  [TYPE]  PFS/ DBASE  II/ FW2/RPD 
FIELDS  <  field  list  >  ]  [<  scope  >  ] 

[FOR  <  condition  >  ]  [WHILE  <  condition  >  ] 

Usage 

EXPORT  creates  files  that  can  only  be  used  by  PFS:FILE,  dBASE  II, 
Framework  II,  or  RapidFile.  You  should  use  the  COPY  command  to  create 
files  that  can  be  read  by  other  software  programs. 

The  records  are  exported  in  indexed  order  if  an  index  file  is  in  use.  For 
PFS:FILE  export,  you  may  use  a  format  (.fmt)  file  to  define  the  screen  for¬ 
mat.  If  a  format  file  is  not  activated  with  SET  FORMAT,  the  default  screen  as 
provided  in  APPEND  or  EDIT  is  used  to  define  the  PFS:FILE  screen  format. 

EXPORT  creates  a  Framework  II  database  frame. 

If  the  dBASE  IV  database  file  was  previously  IMPORTed  from  PFS:FILE,  it 
has  an  associated  format  (.fmt)  file. 

If  a  TO  file  already  exists  and  SET  SAFETY  is  ON,  you  are  warned  before  the 
file  is  overwritten.  If  SET  SAFETY  is  OFF,  dBASE  IV  automatically  over¬ 
writes  the  existing  file. 


NOTE 


dBASE  IV allows  you  to  build  files  with  fields  that  may  be  larger  than 
your  other  software  can  accept.  Although  these  Helds  are  exported, 
they  may  be  truncated  by  other  programs.  Check  the  limitations  of 
other  programs  before  creating  Hies  with  EXPORT. 

For  example,  when  you  EXPORT  a  format  Hie  to  PFS  .FILE,  check  that 
it  does  not  contain  more  than  200  @... SAY.. .GET  commands.  Also,  the 
form  should  not  specify  more  than  21  rows,  and  the  rows  on  your 
form  must  be  between  row  0  and  row  20.  PFS.FILE  cannot  read  a  Hie 
that  exceeds  these  limitations. 


See  Also 


COPY,  IMPORT,  SET  FORMAT,  SET  SAFETY 
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FIND 


FIND  searches  an  indexed  database  file  for  the  first  record  with  an  index  key 
that  matches  the  specified  character  string  or  number.  FIND  conducts  a  very 
rapid  record  search. 


Syntax 

FIND  <  literal  key  > 


Usage 

This  command  positions  the  record  pointer  to  the  first  record  in  an  indexed 
database  file  that  matches  the  character  string  or  number. 

FIND  and  SEEK  both  use  an  index,  either  an  index  (.ndx)  file  or  multiple 
index  (.mdx)  file  tag,  to  quickly  search  for  data  in  a  database  file.  The  index 
used  is  called  the  controlling  or  waster  index,  and  it  is  activated  with  either 
the  SET  INDEX  command,  the  SET  ORDER  command,  or  with  the  INDEX 
clause  of  the  USE  command.  SEEK  can  search  for  an  expression;  FIND 
cannot. 

LOCATE  has  a  similar  function  to  FIND  and  SEEK,  but  processes  the  file 
sequentially  (record-by-record)  and  does  not  require  that  the  file  be  indexed. 
LOCATE  is  generally  slower. 

Because  FIND  does  not  evaluate  expressions  in  the  command  line  the  way 
that  SEEK  does,  you  must  use  a  character  memory  variable  with  the  &,  the 
macro  substitution  function,  when  searching  for  the  variable’s  contents: 

.  FlMgMsrKar 

Substring  or  partial  key  searches  work  only  if  the  search  expression  matches 
the  index  key,  starting  with  the  character  at  the  far  left,  and  if  SET  EXACT  is 
OFF.  FIND  will  fail  to  locate  a  substring  of  the  key  if  SET  EXACT  is  ON, 
because  it  looks  for  an  exact  match  for  the  entire  length  of  the  key.  For 
example,  FIND  Smi  will  find  "Smith*  if  SET  EXACT  is  OFF,  but  not  if  SET 
EXACT  is  ON. 

FIND  respects  the  setting  of  SET  DELETED.  If  SET  DELETED  is  ON,  FIND 
will  not  position  the  record  pointer  on  a  deleted  record. 
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FIND 


Record  Pointer 

If  a  match  is  found,  FIND  positions  the  record  pointer  on  the  matching 
record. 

SET  NEAR  affects  the  positioning  of  the  record  pointer  after  a  FIND.  If  SET 
NEAR  is  ON  (or  if  you  have  NEAR  =  ON  in  the  Config.db  file)  and  a  match¬ 
ing  record  is  not  found,  the  record  pointer  will  be  on  the  very  next  indexed 
record  in  the  file,  just  after  where  FIND  expected  the  matching  record  to  be. 
The  FOUND()  function  will  still  return  a  false  (.F.),  because  the  key  was  not 
found;  EOF(),  however,  will  not  return  a  true  (  T.),  because  the  record 
pointer  is  positioned  to  a  nearly  matching  record  in  the  file. 

If  SET  NEAR  is  OFF,  which  is  the  default  setting,  and  the  specified  character 
string  or  number  is  not  found,  the  message  Find  not  successful  appears  on 
the  screen.  SET  TALK  OFF  suppresses  this  message.  The  record  pointer 
moves  to  the  end  of  the  file,  FOUNDQ  returns  false,  and  EOF()  is  true. 

If  another  file  is  related  with  SET  RELATION  and  the  FIND  is  not  successful, 
the  record  pointer  in  the  related  file  will  always  be  at  the  end  of  the  file, 
whether  NEAR  is  set  ON  or  OFF. 

The  FOUNDQ  function  will  only  return  a  true  for  actual  finds,  regardless  of 
the  status  of  SET  NEAR.  The  EOFQ  function  will  return  a  true  if  SET  NEAR 
is  OFF  and  there  is  no  match.  If  SET  NEAR  is  ON,  EOF()  will  only  return  a 
true  when  the  key  that  is  sought  is  greater  than  all  the  keys  in  the  index. 


Programming  Notes 

Because  the  SEEK  command  accepts  expressions,  it  is  normally  used  in  pro¬ 
gram  files  where  expressions  are  built  by  other  commands  or  functions  and 
passed  to  it.  FIND  is  normally  used  for  ad  hoc  queries  from  the  dot  prompt, 
although  you  can  also  use  FIND  in  program  files. 

Special  Cases 

FIND  ignores  leading  blanks  when  searching  for  a  literal  string.  The  follow¬ 
ing  two  commands  are  identical: 

.  FIN)  A 
.  FIN)  A 

If  you  are  searching  for  a  string  that  contains  leading  blanks,  include  the 
character  string  in  either  single  quote  mark,  double  quote  mark,  or  square 
bracket  delimiters.  You  must  also  include  the  exact  number  of  leading 
blanks  in  the  string: 

.FIN)'  AT 
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FIND 


If  a  memory  variable  contains  leading  blanks,  you  must  enclose  the  macro 
substitution  function  and  variable  in  quotation  marks: 

,'8Kmen\0ry' 

If  you  are  searching  for  a  string  that  begins  with  a  dBASE  delimiter  in  the 
text,  include  the  entire  string  within  another  delimiter: 

.  FIH)  EYa/mdC] 


Examples 


These  examples  use  the  Client  database  Hie,  indexed  on  the  expression 
Lastname  +  Firstname.  To  find  the  first  record  with  a  Lastname  beginning 
with  the  uppercase  letter  G: 


.  USE  CL  ient  INDEX  CLs^ame 
Master  index:  CUSJW€ 

.  Fife  M 
.  ?  Lastname 
fertinez 
.  SET  EXACT  CN 
.  Fife  N 

Find  not  successful 
.  SET  EXACT  OFF 


To  search  for  a  record  for  Paterson  (there  is  no  such  record): 


■  FIND  F’aterscn 
Find  not  successful 
.  ?  BOFO 

.T. 

.  SET  (EAR  (H 
=  FlfC  Fbterscn 
Find  not  successful 
.  ?  EOF  O 
„F. 

.  ?  FCLfCO 
.F. 

.  ?  Lastname 
Fteters 


See  Also 

EOF(),  FOUNDQ,  INDEX,  KEY(),  LOCATE,  LOOKUP(),  MDX(),  NDX(), 
SEEK,  SEEK(),  SET  INDEX,  SET  NEAR,  SET  ORDER,  TAG(),  USE 
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FUNCTION 

FUNCTION  identifies  a  procedure  associated  with  a  user-defined  function. 

Syntax 

FUNCTION  <  procedure  name> 


Usage 

You  may  create  user-defined  functions  to  perform  operations  on  data  items 
that  cannot  be  accomplished  by  the  dBASE  IV  functions  covered  in 
Chapter  4.  When  dBASE  IV  comes  across  a  user-defined  function  in  a  pro¬ 
gram,  it  searches  for  a  FUNCTION  procedure  with  the  same  name  as  the 
user-defined  function,  executes  the  procedure,  and  returns  a  value  to  the 
command  line  that  contained  the  function. 

FUNCTION  procedures  may  be  contained  in  the  current  .dbo  file,  in  a  proce¬ 
dure  file  (if  SET  PROCEDURE  is  used),  or  in  other  open  .dbo  files.  dBASE  IV 
maintains  a  list  of  all  procedures,  including  FUNCTION  procedures,  at  the 
beginning  of  every  object  (  obj)  file. 

FUNCTION  procedures  are  similar  to  other  procedures,  except  that  they 
must  begin  with  the  FUNCTION  command  (just  as  other  procedures  must 
begin  with  a  PROCEDURE  command),  and  they  must  end  with  a  RETURN 
command.  The  user-defined  function  passes  parameters  to  the  FUNCTION 
procedure,  which  must  contain  a  PARAMETERS  command.  The  FUNCTION 
procedure  operates  on  these  parameters,  and  returns  values  to  the  user- 
defined  function  through  the  RETURN  command.  If  you  do  not  supply  the 
RETURN  command  with  an  expression,  it  will  return  a  logical  false  (.F.)  to 
the  user-defined  function. 


As  dBASE  IV  searches  for  a  FUNCTION  procedure  with  the  same  name  as 
the  user-defined  function,  both  the  user-defined  function  and  its  associated 
FUNCTION  must  have  the  same  name,  but  this  must  not  be  the  name  of  a 
dBASE  IV  command  or  function.  As  with  PROCEDURE,  the  name  can  be  up 
to  eight  characters  long  and  must  begin  with  a  letter. 
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FUNCTION 


Examples 

The  following  FUNCTION,  Plus_tax(),  returns  the  final  cost  of  an  item  by 
adding  the  tax  to  the  price.  This  user-defined  function  should  be  included  in 
a  program  file,  and  requires  that  the  item  price  and  tax  be  passed  to  it  as 
parameters. 

FINCTICN  PluBjaxO 

PARWETERS  M_price,  MJax 

M_price  =  (M_price  *  +  Mprice 

RETIRE  OLcost) 

-With  tho  file  available  in  the  current  directory:  ■7~^  ~s  )> 

.  SET  TALK  OFF 
.  HJax  -  .  10 
=  ?  PiLsJaxdCO,  HJax) 

110 


See  Also 

DO,  PARAMETERS,  PROCEDURE,  RETURN 

Chapter  1,  “Essentials,”  contains  further  information  on  user-defined  func¬ 
tions,  including  the  dBASE  IV  commands  that  cannot  be  used  in  FUNCTION 
procedures. 
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GO/ GOTO  positions  the  record  pointer  to  a  specified  record  in  the  active 
database  file. 


Syntax 

GO/GOTO  BOTTOM/TOP  [IN  <  alias  name>  ) 
or 

GO/ GOTO  [RECORD]  <  record  number >  [IN  <  alias  name>  ] 
or 

<  record  number> 


Usage 

If  an  index  is  not  in  use,  TOP  and  BOTTOM  refer  to  the  first  and  last  records 
in  the  database  file.  If  an  index  file  is  in  use  with  the  database,  TOP  and 
BOTTOM  refer  to  the  first  and  last  records  in  the  index  file,  GO  <  record 
number>  refers  to  the  specified  record  number,  and  not  to  a  position  in  the 
index  file.  You  may  also  position  the  record  pointer  to  a  specific  record  by 
issuing  the  numeric  expression  without  the  GO/GOTO  verb. 

With  SET  DELETED  ON,  you  may  GOTO  a  record  that  is  marked  for  deletion 
by  directly  specifying  its  record  number. 

If  a  relation  is  set  up  among  several  files,  moving  the  record  pointer  in  the 
parent  file  with  GOTO  will  reposition  the  record  pointer  in  a  child  database 
file  to  a  related  record.  If  there  is  no  related  record,  the  child  file’s  record 
pointer  will  be  positioned  at  the  end  of  the  file,  and  EOF()  returns  a  true 
(.T.).  Moving  the  record  pointer  in  a  child  file,  however,  does  not  reposition 
the  record  pointer  in  its  parent  file. 


Options 

You  may  reposition  the  record  pointer  in  another  work  area  with  the  IN 
clause.  The  alias  name  must  be  either  the  default  alias  name,  or  the  name 
given  with  the  ALIAS  clause  of  USE,  but  it  cannot  be  a  number  or  letter. 


Programming  Notes 

In  a  network  environment,  the  message  Relation  record  in  use  by  another 
appears  if  the  related  record  is  locked  and  you  attempt  to  modify  its  data. 
You  may  trap  error  number  142  in  an  ON  ERROR  routine,  and  attempt 
another  record  lock. 
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GO/GOTO 


Examples 

The  following  examples  use  the  Client  database  file. 

To  position  the  record  pointer  to  record  five  of  the  Client  database  file: 

.  USE  Client 

.  5 

CLIENT:  Record  to  5 

Use  a  memory  variable  to  retain  the  record  number: 

.  ftrecro  =  RECWO 
5.QD 

.  GO  TCP 

CLIENT:  Record  to  1 

.  GO  Mjvcno 

CUBIT:  Record  to  5 


See  Also 

SET  DELETED,  SET  RELATION,  SKIP 
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HELP 


HELP  is  a  menu-driven  command  that  provides  information  about 
dBASE  IV. 

Syntax 

HELP  [  <  dBASE  IV  keyword  >  ] 


Usage 

The  HELP  command  uses  the  Dbasel.hlp  and  Dbase2.hlp  files  supplied  with 
dBASE  IV. 

The  keyword  must  be  a  dBASE  IV  command,  function,  or  HELP  screen 
name.  You  can  press  FI  Help,  instead  of  typing  HELP,  to  get  the  Help  Table 
of  Contents.  This  displays  the  main  Help  contents.  Use  arrow  keys  to  move 
through  the  menu.  Press  -•-*  to  choose  the  highlighted  option. 

You  can  also  choose  to  go  back  to  reread  earlier  screens,  print  a  screen  of 
information,  view  related  topics,  or  view  just  the  syntax  of  a  command  and 
an  example. 

To  exit  Help,  press  the  Esc  key. 


Example 

You  can  get  HELP  about  the  RUN  command  with: 
.  HELP  RLN 

See  Also 

SET  HELP,  SET  INSTRUCT,  SET  MENU 
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IF 


IF  is  a  structured  programming  command  that  enables  conditional  process¬ 
ing  of  commands.  The  IF  structure  must  terminate  with  ENDIF. 

Syntax 

IF  <  condition  > 

<  commands> 

[ELSE 

<  commands  >  ] 

ENDIF 

Usage 

IF  is  a  valid  command  only  in  programs  and  cannot  be  used  at  the  dot 
prompt. 

Any  structured  commands  within  an  IF. ..ENDIF  structure  must  be  properly 
nested.  Nested  IFs  are  permissible. 

IF  <  condition  >  sets  up  a  condition,  or  logical  expression  such  as  A  —  B 
or  Numvar  <  11,  for  evaluation.  If  the  condition  evaluates  to  a  logical  true 
(.T.),  all  subsequent  commands  are  carried  out  until  an  ELSE  (or  the  ENDIF 
if  no  ELSE  exists)  is  reached.  dBASE  IV  then  executes  the  first  command 
after  ENDIF. 

If  the  condition  evaluates  to  a  logical  false  (.F.),  dBASE  IV  goes  directly  to 
the  ELSE  or  ENDIF,  whichever  it  encounters  first.  Commands  between  the 
ELSE  statement  and  ENDIF  are  executed  if  the  condition  is  false. 

If  there  are  multiple  IFs  in  a  command  structure,  ELSE  refers  to  the  IF 
immediately  preceding  it  in  the  nested  structure. 

The  space  following  ENDIF  on  the  command  line  may  be  used  for  com¬ 
ments;  the  comment  indicator,  &&,  is  not  needed. 
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Example 

Compare  this  example  with  the  example  given  for  the  DO  CASE  command. 
The  following  nested  IF  construct  determines  the  magnitude  of  a  memory 
variable  and  displays  an  appropriate  message: 

IF  M_yalue  >  100 

?  "Value  is  ever  100." 

ELSE 

IF  fl_value  >  10 

?  "Value  is  <ver  10." 

ELSE 

IF  M_veluf  >  1 

?  "Value  is  ever  1." 

ELSE 

?  "\telue  is  1  or  less." 

BDIF 

BDIF 

EM)IF 


See  Also 

DO  CASE,  DO  WHILE,  IIF(),  SCAN 
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IMPORT 


IMPORT  creates  dBASE  IV  files  from  PFS:FILE  forms,  dBASE  II  database 
files,  Framework  II  database  and  spreadsheet  frames,  and  RapidFile  data 
files. 


Syntax 

IMPORT  FROM  <  filename  >  [TYPE]  PFS/DBASEII/FW2/RPD/WK1 

Defaults 

The  filename  must  include  the  file  extension,  if  one  exists.  Usually,  dBASE  II 
database  files  have  a  .dbf  extension,  Framework  II  files  an  fw2  extension, 
RapidFile  data  files  an  .rpd  extension,  and  Lotus  1-2-3  (release  2.x)  files  have 
a  .wkl  extension.  PFS:FILE  forms  do  not  usually  have  an  extension.  The 
newly  created  dBASE  IV  files  are  given  the  same  name  as  the  original  file, 
but  with  a  .dbf  extension.  If  you  import  dBASE  II  files,  the  old  dBASE  II 
database  is  given  a  db2  extension  to  avoid  confusion  with  the  dBASE  IV  file. 

If  a  catalog  is  open,  the  new  file  is  added  to  the  catalog.  Records  created  in 
the  new  database  file  are  limited  to  a  maximum  of  4,000  bytes. 

IMPORT  locates  a  file  on  a  drive  or  directory  you  specify  with  the  SET  PATH 
command.  If  you  do  not  specify  a  drive  or  path,  dBASE  IV  assumes  that  the 
file  to  be  imported  is  on  the  default  drive  and  directory. 

Usage 

To  make  sure  that  you  impcrt  files  correctly,  check  the  following  conditions 
before  using  the  IMPORT  command: 

■  255  data  items  per  form.  You  can  have  up  to  255  fields  in  a  record. 
(Notice,  however,  that  headings  and  comments  in  your  PFS:FILE  form 
are  also  converted  to  fields.) 

■  254  characters  per  data  item.  254  is  the  maximum  length  for  character 
fields  in  dBASE  IV. 

IMPORTing  a  PFS:FILE  form  creates  a  database  (  dbf)  file  and  a  format 
(.fmt)  file.  Both  have  the  same  filename,  and  are  assigned  their  default  file 
extensions. 


See  Also 

APPEND  FROM,  COPY,  EXPORT,  SET  FORMAT,  USE 
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INDEX 


INDEX  creates  an  index  in  which  records  from  a  database  file  are  ordered 
alphabetically,  chronologically,  or  numerically. 


Syntax 

INDEX  ON  <  key  expression  >  TO  <  .ndx  filename  >  / 

TAG  <  tag  name>  [OF  <  .mdx  filename  >  ]  [UNIQUE] 

[DESCENDING] 

Defaults 

Unless  you  specify  otherwise  as  part  of  the  filename,  the  default  drive  and 
directory  are  assumed.  If  you  give  a  filename  without  an  extension,  the 
default  .ndx  or  .mdx  extension  is  written. 

If  you  type  only  INDEX  ♦♦  (that  is,  without  any  other  keywords  or  options), 
dBASE  IV  prompts  for  the  index  expression,  which  corresponds  to  the  ON 
clause,  and  the  destination,  which  corresponds  to  the  TO  clause. 

When  SET  SAFETY  is  ON  (the  default),  dBASE  IV  displays  a  warning  prompt 
before  overwriting  an  index  (.ndx)  file,  or  a  tag  with  the  same  name. 

If  you  use  TAG,  but  do  not  provide  an  .mdx  filename  with  the  OF  clause, 
dBASE  IV  creates  the  tag  in  the  production  .mdx  file. 

INDEXing  occurs  in  ascending  order,  unless  you  use  the  DESCENDING 
option.  You  may  build  .mdx  tags  only  with  the  DESCENDING  option. 

Usage 

The  index,  which  is  written  to  disk  as  either  an  index  (.ndx)  file  or  as  a  tag  in 
a  multiple  index  (.mdx)  file,  contains  the  key  values  and  the  corresponding 
record  number  for  each  record  in  the  database  file. 

Indexed  database  files  allow  you  to  position  the  record  pointer  directly  to 
the  first  record  whose  data  matches  an  expression  given  with  the  FIND  or 
SEEK  commands,  or  with  the  LOOKUP()  or  SEEK()  functions. 

A  multiple  index  (.mdx)  file  may  contain  up  to  47  tags,  each  of  which 
imposes  an  index  order  on  the  database  file.  Tag  names  follow  the  same 
naming  conventions  as  variable  names:  they  may  be  up  to  ten  characters 
long,  must  begin  with  a  letter,  and  may  contain  letters,  numbers,  and  under¬ 
scores.  Index  filenames  (both  .ndx  and  .mdx)  follow  the  naming  conventions 
for  all  filenames:  they  may  be  up  to  eight  characters  long,  and  may  only  con¬ 
tain  characters  allowed  by  DOS. 
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INDEX 


A  production  multiple  index  file  is  an  mdx  file  opened  whenever  the  data¬ 
base  file  is  USEd.  Each  database  file  may  have  one  production  mdx  file.  The 
production  multiple  index  file  has  the  same  name  as  the  database  file,  but 
has  an  mdx,  rather  than  .dbf,  file  extension.  The  database  file  header  con¬ 
tains  a  flag  that  indicates  the  presence  of  a  production  .mdx  file. 

To  create  an  .ndx  file,  specify  TO  <  filename  >  .  To  create  a  tag  in  the  pro¬ 
duction  .mdx  file,  specify  TAG  <  tag  name>  .  To  write  the  index  to  an  mdx 
file  that  is  not  the  production  .mdx  file,  specify  TAG  <  tag  name>  OF 
<  .mdx  filename  >  . 

The  physical  order  of  the  records  in  the  original  database  file  on  disk  is  not 
changed  by  the  INDEX  command.  The  index  file  contains  the  index  key  val¬ 
ues  and  the  corresponding  record  number  for  each  record  in  the  database 
file.  The  controlling  index  controls  the  movement  of  the  record  pointer  in 
the  database  file. 

Once  you  create  an  index,  it  becomes  the  new  controlling  index,  and  records 
will  appear  in  the  new  index  order.  To  change  the  controlling  index,  use  the 
SET  INDEX  or  SET  ORDER  command.  Additional  active  index  files  have 
no  effect  on  record  pointer  movement,  and  are  open  only  so  they  can  be 
updated  when  data  in  their  keys  are  added,  changed,  or  deleted  in  the  data¬ 
base  file.  Whenever  changes  are  made  to  a  database  file  that  affect  the  key, 
the  associated  index  file  must  be  open  to  log  the  changes. 

When  you  create  an  ascending  index,  the  key  expression  may  be  a  single 
field  or  any  valid  dBASE  expression.  The  maximum  length  of  the  key  expres¬ 
sion  is  220  characters.  The  maximum  length  of  the  key,  the  result  of  the  eval¬ 
uated  index  key  expression,  is  100  characters. 

The  data  type  of  the  index  ley  expression  determines  whether  records  will 
be  ordered  chronologically  (date  expressions),  numerically  (numeric  expres¬ 
sions),  or  in  ASCII  order  (character  expressions).  When  the  index  key 
expression  includes  several  fields,  they  must  all  be  converted  to  the  same 
data  type.  You  can  use  dBASE  functions  to  convert  fields  to  a  matching  type. 
Some  of  the  functions  most  commonly  used  in  creating  index  key  expres¬ 
sions  are  STR(),  SUBSTRQ,  CTOD(),  DTOC(),  DTOS(),  YEAR(),  MONTH(), 
DAY(),  and  VAL(). 

Options 

The  UNIQUE  option  is  the  same  as  issuing  SET  UNIQUE  ON  before  an 
INDEX.  When  several  records  have  the  same  value  on  the  key  field,  only  the 
first  record  that  dBASE  IV  encounters  with  that  value  is  included  in  the 
.ndx  file. 

Whenever  you  REINDEX  an  .ndx  file  that  was  created  with  UNIQUE,  the  file 
retains  its  UNIQUE  status,  regardless  of  whether  SET  UNIQUE  is  ON  or  OFF. 
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DESCENDING  will  build  an  .mdx  tag  in  descending  ASCII  order.  The 
DESCENDING  option  can  only  refer  to  the  entire  index  expression,  not  to 
one  element  in  the  expression,  such  as  a  field.  You  may  not  build  an  .ndx  file 
with  the  DESCENDING  option. 


Tips 

You  can  specify  index  expressions  that  convert  field  types.  For  example,  if 
you  wanted  to  INDEX  a  date  field  chronologically  and  have  the  last  names  in 
alphabetical  order  for  each  date,  you  could  create  the  following  expression: 

INDEX  ON  DTOS(  <  date  >  )  +  Last_name  TO  <  index  filename> 

The  key  expression  must  evaluate  to  a  fixed-length  key.  dBASE  IV  does  not 
prohibit  you  from  creating  an  index  with  a  variable  length  key,  but  the  index 
may  not  be  reliable.  When  creating  an  index,  always  be  sure  to  give  a  spe¬ 
cific  fixed  length  with  functions  that  accept  a  length  parameter,  such  as 
STR()  and  SUBSTRQ. 

SORT  and  INDEX  both  reorder  the  records  in  a  database  file,  but  SORT 
creates  a  new  physical  database  file  that  is  written  on  disk.  A  SORT  opera¬ 
tion  is  analogous  to  COPYing  an  INDEXed  database  file. 

Operations  that  move  sequentially  through  the  database  file  are  usually 
slower  if  an  index  is  open.  SET  ORDER  TO  0  if  you  are  not  using  the  index 
to  position  the  record  pointer,  but  still  want  to  update  the  index  keys. 


Special  Cases 

If  you  use  TAG,  but  do  not  provide  an  .mdx  filename  with  the  OF  clause, 
dBASE  IV  checks  the  database  file  header  for  the  existence  of  a  production 
.mdx  file.  If  a  production  .mdx  file  exists,  dBASE  IV  creates  the  tag  in  that 
production  .mdx  file.  If  it  does  not  find  a  production  .mdx  file,  it  creates 
one.  While  attempting  to  create  the  new  .mdx  file,  it  may  find  another  mdx 
file  with  the  same  name  as  the  .mdx  file  it  is  attempting  to  create.  In  this 
case,  it  updates  the  database  file  header  to  show  the  presence  of  this  produc¬ 
tion  .mdx  file,  without  creating  a  new  file. 

If  you  use  the  OF  clause,  and  the  .mdx  file  is  not  open,  it  will  be  opened 
before  the  index  is  created.  If  the  .mdx  file  cannot  be  found,  a  new  .mdx  file 
is  created  with  the  filename  stated  in  the  OF  clause. 

If  you  do  not  use  TAG,  an  .ndx  file  is  created. 

INDEX  ignores  filters  set  with  SET  FILTER  or  SET  DELETED.  All  records  of 
the  database  file  are  included  in  the  index,  even  those  marked  for  deletion  or 
not  satisfying  the  filter  condition. 
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INDEX 


You  can  create  an  index  on  memory  variables  and  fields  from  other  open 
database  files.  Indexes  that  reference  data  not  in  the  current  database  file, 
however,  are  not  automatically  updated  when  data  in  the  key  is  changed. 

If  a  catalog  is  open  when  an  ndx  or  .radx  file  is  created,  the  index  file  is 
added  to  the  catalog.  Index  tags  contained  within  an  .mdx  file  are  not,  how¬ 
ever,  added  to  the  catalog. 

In  a  network  environment,  the  database  file  must  be  in  exclusive  use  before 
INDEXing.  If  the  file  is  not  USEd  EXCLUSIVEly,  the  error  message 

Exclusive  use  of  database  is  required  appears. 


Examples 

To  index  the  TVansact  database  file  bv  Client. id: 


.  USE  Transact 

.  INDEX  CN  CL  ientud  TO  QjsJd 

10CK  indexed  12  Records  indexed 

.  LIST 

TRANSACT:  Record  No  9 


Record# 

CUBIUD 

CRDERJD 

DATEJRANS 

IWDICED 

TUTALBILL 

9 

AG0CC5 

87-113 

03/24/87 

.T. 

125.00 

1 

A10Q25 

87-105 

02/03/87 

.T. 

185D.00 

12 

A1CE25 

87-116 

04/10/87 

.F. 

1500.00 

10 

B120C0 

87-114 

03/30/8 7 

.F. 

450.00 

2 

conn 

87-105 

02/10/87 

.T. 

1203.00 

7 

1  (TTTP 

87-111 

03/11/87 

.F. 

1000.00 

To  index  the  file,  grouping  together  similar  Client.ids  and  order  of  amount 
of  each  transaction: 


.  INDEX  CN  CL  ierrtud  +  STRCTotaLbiLL,  10^2)  TO  dy_&nt 
IdK  indexed  12  Records  indexed 

.  LIST 

TRANSACT:  Record  No  9 


Record# 

CLIENLID 

CRD6RJD 

DATEJRANS 

INK3ICED 

TOTALBILL 

9 

A0QDQ5 

87-113 

03/24/87 

•T. 

125.00 

12 

A1Q325 

87-116 

04/10/87 

.F. 

1500.00 

1 

A10Q25 

87-105 

02/03/87 

.T. 

1850.00 

10 

B1200D 

87-114 

03/30/87 

.F. 

450.00 

11 

CQ0D01 

87-115 

04/01/8 7 

.F. 

165.00 

7 

i  mTTP 

87-111 

03/11/87 

.F. 

1003.00 
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INDEX 


If  you  want  an  alphabetical  list  of  all  Client_ids,  use  the  UNIQUE  option: 

.  IWEX  OV  Cl  ierrtJd  TO  Cl  ients  INIGLE 
1CEK  indexed  7  Records  indexed 

.  LIST  Cl  ient_id 
TRANSACT:  Record  to  9 

Record#  ClientJd 
9  /am 5 

1  A1CC25 
10  B12QD 

2  C00001 

3  cane 
5  LOOODI 
7  i  nrrn? 


To  create  an  index  TAG  of  Transact  in  reverse  chronological  order: 

.  IMEX  CN  Date-trans  TAG  Recent  DESCBWNS 
102K  indexed  12  Records  indexed 

.  LIST 

TRANSACT:  Record  to  12 


Record# 

ojbiud 

CRD6RJD 

DATEJRANS 

IN/31  CED 

TOTAL-BILL 

12 

A1CD25 

87-116 

04/10/87 

.F. 

15CD.00 

11 

enrol 

87-115 

04/01/87 

.F. 

165.00 

10 

B12C00 

87-114 

CB/3Q/8 7 

.F. 

450.00 

9 

/cars 

87-113 

03/24/87 

•T. 

125.00 

8 

unm 

87-112 

□3/20/87 

.T. 

700.00 

1 

A1CD25 

87-105 

02/03/87 

.T. 

1850.00 

See  Also 

CLOSE,  COPY  INDEX,  COPY  TAG,  DELETE  TAG,  FIND,  KEY(),  MDX(), 
NDX(),  ORDER(),  REINDEX,  SEEK,  SET  INDEX,  SET  NEAR,  SET  ORDER, 
SET  UNIQUE,  SORT,  TAG(),  USE 

The  SORT  command  explains  the  differences  between  INDEX  and  SORT  in 
greater  detail. 
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INPUT 


INPUT  is  primarily  used  in  dBASE  programs  to  prompt  a  user  to  enter  an 
expression  from  the  keyboard.  Data  entry  is  terminated  by  a 


Syntax 

INPUT  [  <  prompt  >  ]  TO  <  memvar  > 


Usage 

This  command  creates  a  memory  variable  that  contains  the  expression 
entered  in  response  to  the  prompt. 

The  prompt  must  be  a  character  expression.  If  the  prompt  is  a  literal  rather 
than  a  memory  variable,  it  must  be  delimited  by  single  quotes  ('  '),  double 
quotes  (*  *),  or  square  brackets([  ]). 

You  may  enter  any  valid  dBASE  expression  in  response  to  the  INPUT  com¬ 
mand.  The  type  of  expression  entered  determines  the  type  of  memory  vari¬ 
able  created.  For  instance,  if  you  enter  a  number  in  response,  a  type  N 
numeric  variable  is  created. 

You  must  enter  a  response  followed  by  ♦♦.  If  you  press  ♦♦  without  first  mak¬ 
ing  an  entry,  the  prompt  displays  again. 


Programming  Notes 

If  the  response  must  be  character  type  data,  use  ACCEPT,  WAIT,  or  @...GET 
with  the  PICTURE  option.  ACCEPT  assumes  that  all  user  response  is  charac¬ 
ter  and  doesn’t  require  delimiters. 

If  you  use  an  INPUT  command  that  requires  a  date  response,  include 
instructions  in  the  prompt  to  enter  the  date  in  curly  braces,  which  are  the 
date  delimiter.  If  you  enter  a  character  response,  you  should  use  the  CTOD() 
function  to  convert  the  character  variable  to  a  date  variable. 

If  a  memory  variable  of  the  same  name  already  exists,  it  is  overwritten, 
unless  you  declare  one  variable  PUBLIC  and  the  other  PRIVATE. 


See  Also 

@,  ACCEPT,  PRIVATE,  PUBLIC,  READ,  STORE,  WAIT 
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INSERT  adds  a  single  new  record  to  the  database  file  at  the  current  record 
location. 


Syntax 

INSERT  [BEFORE]  [BLANK] 

Usage 

INSERT  displays  the  new  record  for  full-screen  data  entry.  You  may  enter 
data  into  this  record  only.  The  new  record  is  inserted  immediately  after  the 
current  record.  For  instance,  if  the  current  record  is  number  5,  INSERT 
creates  a  new  record  6;  the  old  record  6  becomes  record  7,  and  so  on. 

In  two  instances,  INSERT  works  like  APPEND  and  will  add  multiple  records 
at  the  end  of  the  file  one  at  a  time:  if  the  file  is  indexed,  and  if  the  record 
pointer  is  already  at  the  end  of  file. 

Enter  data  into  a  memo  field  by  placing  the  cursor  on  it  (labeled  memo 
on  the  screen)  and  pressing  Ctrt-PgDn.  Leave  the  memo  field,  by  pressing 
Ctrl-End  (to  save)  or  Esc  (to  exit  without  saving  changes).  While  editing  the 
memo  field,  use  the  same  control  keys  as  MODIFY  COMMAND.  Press  FI  to 
toggle  on  and  off  the  menu  displaying  the  keys  you  can  use. 

Arrow  keys  move  the  cursor  within  a  record.  Esc  abandons  the  process  with¬ 
out  inserting  a  new  record,  displaying  the  message  Record  is  not  inserted. 
Ctrl-End  terminates  the  process  and  completes  the  record  insertion. 


Options 

The  BEFORE  clause  inserts  a  new  record  just  before  the  current  record, 
rather  than  after  the  current  record.  For  instance,  if  the  current  record  is 
number  5,  INSERT  BEFORE  creates  a  new  record  5;  the  old  record  5 
becomes  record  6,  and  so  on. 

If  you  include  BLANK,  a  new  record  is  INSERTed,  but  you  do  not  enter  full¬ 
screen  mode.  An  empty  record  is  placed  in  the  database  file.  You  may  add 
data  later  using  the  BROWSE,  CHANGE,  EDIT,  or  REPLACE  command. 


Tips 

To  copy  the  contents  of  the  preceding  record  to  the  INSERTed  record,  use 
SET  CARRY  ON  before  INSERTing  records. 

If  SET  AUTOSAVE  is  OFF,  the  directory  entry  for  the  active  database  file  may 
not  reflect  all  new  records  until  the  file  is  closed.  If  SET  AUTOSAVE  is  ON, 
the  directory  on  disk  is  updated  after  each  new  record  is  added. 
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INSERT 


Special  Cases 

In  a  network  environment,  INSERT  requires  exclusive  use  of  the  database 
file. 


Example 

To  insert  a  new  record  immediately  before  record  4  (that  is,  to  create  a  new 
record  4)  in  the  Client  database  file,  type  the  following: 

.  USE  Client 
.  GO  4 

CUB/T:  Record  to  4 

.  INSERT  BEFORE 


See  Also 

@,  APPEND,  CHANGE,  EDIT,  MODIFY  COMMAND,  READ,  SET  AUTOSAVE, 
SET  CARRY,  SET  FORMAT 
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JOIN  creates  a  new  database  file  by  merging  specified  records  and  fields 
from  two  open  database  files. 


Syntax 

JOIN  WITH  <  alias  >  TO  <  filename  >  [FIELDS  <  field  list  >  ] 
FOR  <  condition  > 


Defaults 

The  TO  filename  must  include  the  drive  and  directory  location  if  the  file  is 
not  in  the  current  directory.  A  .dbf  file  extension  is  assumed  unless  you  spec¬ 
ify  otherwise. 

Usage 

When  JOINing  an  active  file  with  an  open  file  from  an  unselected  work  area, 
identify  the  second  file  by  its  alias  name.  The  alias  name  may  be  the  same  as 
the  filename. 

The  field  list  may  consist  of  any  type  of  field  from  both  files  except  memo 
fields.  If  you  try  to  join  memo  fields,  you  will  get  the  message  Operation 
with  memo  field  invalid. 

The  record  pointer  is  set  to  the  first  record  in  the  active  file.  Then,  each 
record  in  the  second  file  is  evaluated  to  see  if  it  matches  the  FOR 
<  condition  >  .  If  the  specified  condition  is  true  (  T.),  a  new  record  is  added 
to  the  new  file.  When  all  records  in  the  second  file  are  scanned,  the  record 
pointer  in  the  active  file  advances  to  the  second,  and  the  process  is  repeated. 
This  continues  until  all  records  in  the  active  file  are  processed.  This  opera¬ 
tion  can  take  a  long  time  for  large  files. 

If  you  do  not  specify  a  field  list,  field  assignments  are  first  made  from  the 
active  file.  Then,  fields  are  assigned  from  the  second  file  until  the  255-field 
limit  is  reached.  Duplicate  field  names  appear  only  once  in  the  new  file. 

JOIN  updates  a  catalog,  if  it  is  open  and  SET  CATALOG  is  ON. 

Tips 

Do  not  use  the  single  letters  A  through  J,  or  the  letter  M,  as  database 
filenames,  because  they  are  reserved  for  alias  names.  For  example,  AAis  a 
valid  database  filename  whereas  A  is  not. 
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JOIN 


Make  sure  you  have  enough  room  when  JOINing  two  files.  Two  database  files 
can  be  JOINed  such  that  the  new  file  exceeds  the  available  disk  space.  The 
new  JOINed  file  can  become  quite  large  if  you  do  not  carefully  choose  the 
specified  condition.  For  example,  if  two  1,000-record  files  were  JOINed 
and  the  specified  condition  were  always  true,  1,000,000  records  would  be 
created! 


Special  Cases 

If  both  files  have  a  field  name  in  common  and  you  want  to  include  a  field 
from  the  unselected  work  area,  precede  the  field  name  with  the  alias  name. 

You  may  also  use  the  SET  FIELDS  command  before  JOIN,  rather  than  giving 
a  field  list.  Only  the  fields  listed  in  SET  FIELDS  will  be  included  in  the  new 
database  file. 


Examples 

You  can  combine  the  Client  database  file  with  the  Transact  database  file  and 
form  a  new  database  file,  New  file,  to  include  client  and  order  IDs,  client 
name,  order  date,  and  the  amount  of  the  order. 

.  USE  Client 
.  USE  Transact  IN  2 

In  the  following  JOIN  command  example,  Newfile  is  the  new  database  file 
created  with  the  fields  Qient_id,  Client,  Date.trans,  Total.bill,  and  Order_id 
from  the  two  database  files,  Client. dbf  and  Transact. dbf.  Because  Date_trans, 
Total. bill,  and  Order.id  aie  found  only  in  'Transact,  which  is  in  the  unselec¬ 
ted  work  area,  you  have  to  let  dBASE  IV  know  where  to  find  these  fields. 

You  can  identify  fields  in  work  area  1  by  the  alias  A  or  Client,  or  work  area  2 
by  the  alias  B  or  Transact. 
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JOIN 


.  JOIN  UZ7H  Transact  TO  Newfile  FOR  CL  ient_id=tr>CL  ient_id  FIELDS  CL  ientL_id^j 
■Ci  d-XtitzJrans,  9->TotaLJ>iLL ,  B-JOrdar_id  ** 

12  retfcrds  joined 
.  USE  NewfiLe 
.  DISPLAY  STRUCTURE 


(7> 


Structure  for  database:  C:\DATA^W  FILE. DBF 

Nuitoer  of  data  records:  12 

/\ 

Date  of  last  ixxfete  :  11/23/87 

Field  Field  teme 

T>pe 

Width 

Dec 

Index 

1  CUBfUD 

Character 

6 

N 

2  CLIENT 

Character 

30 

N 

3  DATEJTVNS 

Date 

8 

N 

4  TOTALBILL 

Nuneric 

8 

2 

N 

5  0RDERJD 

Character 

6 

N 

**  Total  ** 

59 

.  LIST  TEXT  5  CL  ient ,  DatzJrarts,  Crdar_id 


Record#  Client 

1  BAILEY  &  BAILEY 

2  BAILEY  &  BAILEY 

3  L.  G.  ELJJi  8  ASSOCIATES 

4  L.  G.  BlLM  a  ASSOCIATES 

5  L.  G.  BLLM  8  ASSOCIATES 


Date_trans  TotaLbill  Order_id 

03/09/87  415.CD  87-109 

05/20/87  700. CD  87-112 

02/10/87  1200.00  87-106 

02/23/87  1250.00  87-108 

04/01/87  165.00  87-115 


See  Also 

SET  FIELDS,  SET  RELATION 
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LABEL  FORM 


LABEL  FORM  uses  a  specified  label  format  file  designed  with  MODIFY 
LABEL  to  print,  display,  or  write  labels  to  a  file  on  disk. 


Syntax 

LABEL  FORM  <  label  filename  >  /?  [SAMPLE] 

[<  scope  >  ]  [FOR  <  condition  >  ]  [WHILE  <  condition  >  ] 

[TO  PRINTER/TO  FILE  <  filename  >  ] 

Defaults 

Unless  the  file  is  on  the  default  drive  or  a  path  is  set,  the  filename  must 
include  the  drive  designator  and  path.  dBASE  IV  first  searches  for  an  .lbo, 
then  an  .lbg,  and  then  an  .lb  1  extension  for  the  label  form  file. 

If  you  installed  the  Ascii. pr2  printer  driver,  the  file  created  by  the  TO  FILE 
option  will  have  a  .txt  extension.  If  you  installed  any  other  printer  driver,  the 
file  created  by  TO  FILE  will  have  a  .prt  extension.  Files  with  .prt  extensions 
may  contain  embedded  escape  sequences  specific  to  the  installed  printer. 

Unless  otherwise  specified  by  the  scope,  the  FOR  or  WHILE  clause,  or  an 
active  filter,  labels  are  printed  for  all  records  in  the  active  database  file. 

Usage 

The  label  template  that  you  created  with  CREATE/MODIFY  LABEL  is  con¬ 
tained  in  a  file  with  an  .lbl  extension.  The  dBASE  code  that  was  generated  is 
contained  in  a  file  with  an  lbg  extension.  When  you  first  run  labels  with  the 
LABEL  FORM  command,  the  .lbg  file  is  compiled  to  an  .lbo  file.  LABEL 
FORM  executes  the  labels  from  the  .lbo  file. 

Options 

Use  the  SAMPLE  option  to  print  test  labels  to  ensure  proper  alignment  of  the 
labels  in  the  printer.  A  single  row  of  test  labels  is  displayed  using  the  charac¬ 
ter  .r  rather  than  data  from  the  database  file.  You  may  repeat  the  process  as 
many  times  as  necessary  by  responding  Y  when  asked  Do  you  want  more 
sample*?  When  you  respond  with  N,  labels  begin  printing  using  data  from 
the  file. 
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LABEL  FORM 


Use  the  TO  FILE  option  to  send  the  labels  to  a  disk  file,  rather  than  to  the 
printer  or  screen.  If  you  direct  the  output  to  a  disk  file  with  the  TO  FILE 
option,  and  you  have  installed  the  ASCII  text  printer  driver  (Ascii. pr2), 
dBASE  IV  creates  a  file  with  a  .txt  extension.  The  .txt  file  does  not  contain 
any  embedded  escape  codes.  If  you  have  installed  any  other  driver, 
dBASE  IV  creates  a  file  with  a  .prt  extension  The  .prt  file  may  contain 
embedded  escape  sequences  specific  to  the  installed  printer. 

The  question  mark,  ?,  is  called  the  query  clause.  Use  this  to  activate  a  menu 
of  label  files  to  choose  from. 

See  Also 

CREATE/ MODIFY  LABEL,  SET  PRINTER 

Chapter  5,  “System  Memory  Variables",  includes  a  discussion  of  variables, 
such  as  _pdriver,  which  affect  printed  output. 

Using  the  Menu  System  discusses  the  label  generator  in  more  detail. 
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LIST/DISPLAY 


Use  LIST/DISPLAY  to  view  the  contents  of  a  database  file  in  an  unformatted 
columnar  list. 


Syntax 

LIST/ DISPLAY  [[HELDS]  <  expression  list  >  ]  [OFF] 

[<  scope  >  ]  [FOR  <  condition  >  ]  [WHILE  <  condition  >  ] 
[TO  PRINTER/TO  HLE  <  filename  >  ] 


Defaults 

LIST  shows  all  records,  unless  limited  by  the  scope,  a  FOR  or  WHILE  clause, 
SET  FILTER,  or  SET  DELETED.  DISPLAY  shows  only  the  current  record, 
unless  given  the  scope  or  a  FOR  or  WHILE  clause. 

Usage 

LIST  and  DISPLAY  ALL  are  nearly  identical,  except  that  DISPLAY  pauses 
after  each  screen’s  display  and  LIST  does  not.  After  each  screen,  DISPLAY 
prompts  Press  any  key  to  continue... 

To  halt  a  LIST  or  DISPLAY,  press  Ctri-S  (with  SET  ESCAPE  ON).  Press  any 
key  to  resume  LISTing. 

To  abandon  a  LIST,  press  Esc  (with  SET  ESCAPE  ON). 

The  contents  of  memo  fields  are  not  displayed  unless  explicitly  named  in  the 
FIELDS  list.  Instead,  the  field  name  appears  above  the  word  memo  (all  low¬ 
ercase)  if  there  is  no  text  in  the  memo  field,  or  MEMO  (all  uppercase)  if 
there  is  text  in  the  memo  field.  If  memo  fields  are  named  in  the  expression 
list,  their  contents  are  displayed  in  50-character  wide  columns.  Use  the  SET 
MEMOWIDTH  command  to  change  this  default  display  width. 

When  you  LIST  or  DISPLAY  a  record  that  is  greater  than  80  characters,  the 
contents  on  the  screen  wrap  around  to  the  next  line  and  may  break  up  a 
field  onto  two  or  more  lines. 


Options 

TO  PRINTER  directs  command  output  to  the  printer,  and  TO  HLE  directs 
the  output  to  a  file  on  disk. 

The  OFF  option  suppresses  the  record  numbers. 
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Special  Cases 

If  SET  HEADING  is  ON,  each  column  has  a  heading.  If  the  displayed  item  is 
the  result  of  an  expression  involving  a  field  (for  example  Cost/25),  the  col¬ 
umn  heading  is  the  same  as  the  expression. 

The  heading  appears  just  as  you  type  it.  For  example,  to  have  the  heading  in 
all  capital  letters,  type  DISPLAY  FI  ELD  1.  For  upper  and  lower  case  headings, 
type  DISPLAY  Field  1. 


Example 


.  USE  Stock 
=  SET  tEADINS  OFF 

.  LIST  OFF  STR(0ty^5/0)  +  SPACECD  +  STRCItenuxst ,3^2)  + 
FCRltenuxsst  >  300 


STOCX:  Record  No 

1  12CD.CD 

1  650. CD 

1  1203.00 

1  1250.00 

1  1250.00 

1  10CD.CD 

2  350.00 

1  1500.00 

1  1000.00 


1 

90FA,  6-ROT 
SOFA,  6-RXJT 
SOFA,  8-ROT 
CHAIR,  D6SK 
CHAIR,  DESK 
CHAIR,  DESK 
CHAIR,  SIDE 
DE3C,EXECLnTVE  5-ROT 
OAIR,  DESK 


See  Also 

SET  HEADING,  SET  MARGIN,  SET  MEMOWIDTH 
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LIST/DISPLAY  FILES 


LIST/DISPLAY  FILES  displays  directory  information  similar  to  that  displayed 
by  the  DOS  DIR  command. 

Syntax 

LIST/DISPLAY  FILES  [LIKE  <  skeleton  >  ] 

[TO  PRINTER/TO  FILE  <  filename  >  ] 

Defaults 

If  you  do  not  specify  a  filename  or  skeleton,  LIST/DISPLAY  FILES  provides 
directory  information  on  database  files  only. 

Usage 

For  database  files,  this  command  displays  the  files,  number  of  records,  date 
of  last  update,  file  size  (in  bytes),  total  number  of  files  displayed,  total  num¬ 
ber  of  bytes  for  the  displayed  files,  and  the  total  number  of  bytes  remaining 
on  disk. 

The  directory  does  not  reflect  changes  to  newly  changed  files  until  after  the 
file  is  closed. 

LIST/DISPLAY  FILES  is  an  alternate  to  DIR,  but  DIR  does  not  accept  the  TO 
FILE  or  TO  PRINTER  options.  LIST/ DISPLAY  FILES  also  allows  the  output 
to  be  routed  to  a  disk  file  or  to  the  printer. 


Examples 


.  LIST  FILES 

Database  Files 

H  Records 

Last  Ifcrfate 

Size 

CUBfi-.DeF 

8 

11/05/82] 

1570 

STOCK.  DBF 

17 

11/05/8} 

1569 

TRWSACT.CeF 

12 

[11/C5/jp 

554 

3693  bytes  in  3  files 

8357056  bytes  retaining  an  d"ive 

See  Also 

DIR,  FILEQ 


c. 


2-158 


COMMANDS 


PAGE:  159  SESS:  9  Ued  Hay  11  09:23:11  1988 
sk2/a I  I j ob2/CLS_manha t /GRP_manha t / JOBjnan t angref /DI V_l rchap2d 

LIST/DISPLAY 

HISTORY 


LIST/DISPLAY  HISTORY  outputs  a  list  of  commands  that  have  been 
executed  and  are  stored  in  the  history  buffer. 


Syntax 

LIST/DISPLAY  HISTORY  [LAST  <  expN>  ] 

[TO  PRINTER/TO  FILE  <  filename  >  ] 

Defaults 

The  default  number  of  commands  stored  in  the  history  buffer  is  20.  You  can 
alter  this  number  with  SET  HISTORY. 

Usage 

DISPLAY  pauses  after  each  screen;  LIST  scrolls  without  pausing. 

This  command  lets  you  view  previously  executed  commands  from  the  least 
recent  to  the  most  recent. 


Options 

LIST/DISPLAY  HISTORY  displays  all  commands  in  the  history  buffer,  unless 
you  limit  the  number  by  including  the  LAST  option.  In  this  case,  it  displays 
only  the  last  <  expN>  commands. 

TO  PRINTER  directs  command  output  to  the  printer,  and  TO  FILE  directs 
the  output  to  a  file  on  disk. 


See  Also 

SET  HISTORY 
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LIST/DISPLAY 

MEMORY 


LIST/DISPLAY  MEMORY  provides  information  on  how  dBASE  IV  is  using 
your  computer’s  memory. 


Syntax 

LIST/ DISPLAY  MEMORY  [TO  PRINTER/TO  FILE  <  filename  >  ] 

Usage 

DISPLAY  MEMORY  pauses  after  every  screen  and  displays  the  prompt  Press 
any  key  to  continue...  LIST  MEMORY  does  not  pause  after  each  screen. 

The  display  for  numeric  variables  contains  both  the  number  and  the  type 
(type  F  or  type  N). 

This  command  shows  the  number  and  names  of  active  memory  variables  and 
elements;  the  public  or  private  status  of  each;  the  values  contained  in  each 
variable  or  element;  the  names,  definitions,  and  amount  of  memory  used  by 
all  active  windows,  popups,  menus,  and  pads;  the  settings  for  all  system 
memory  variables;  and  the  amount  of  memory  still  available. 

The  number  of  memory  variables  you  can  have  is  the  product  of  the 
MVBLKSIZE  and  MVMAXBLKS  settings,  which  are  contained  in  the 
Config.db  file.  MVBLKSIZE  is  the  number  of  memory  variable  slots  each 
block  may  contain,  and  MVMAXBLKS  is  the  maximum  number  of  blocks  in 
memory  that  may  be  allocated  for  memory  variables.  If  MVBLKSIZE  *  50 
and  MVMAXBLKS  =■  10  (the  default  settings),  you  can  STORE  up  to  10 
blocks  of  50  variables  each,  or  a  total  of  500  memory  variables. 

Memory  variable  blocks  aie  allocated  as  they  are  needed.  When  one  block  is 
full,  a  second  block  is  allocated.  Additional  blocks  are  allocated  until  the 
maximum  number  of  blocks,  which  is  set  with  MVMAXBLKS,  is  reached. 
Each  memory  variable  slot  requires  56  bytes;  when  the  first  block  is  allo¬ 
cated,  dBASE  reserves  enough  space  for  50  memory  variables,  which  is  2,800 
bytes  of  memory. 

Each  array  that  you  DECLARE  takes  one  memory  variable  slot  only.  A  spe¬ 
cial  block  is  allocated  for  each  array  to  hold  the  elements.  Therefore,  the 
number  of  array  elements  do  not  take  away  from  the  number  of  slots  initial¬ 
ized  by  MVBLKSIZE  and  MVMAXBLKS. 

If  a  memory  variable  is  date,  logical,  or  numeric,  the  data  is  contained 
within  the  memory  variable  slot.  If  the  memory  variable  is  character,  the 
memory  variable  slot  contains  a  pointer  to  another  area  in  memory  that  con¬ 
tains  the  character  string. 
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LIST/DISPLAY  MEMORY 


For  every  dBASE  session,  runtime  symbols  are  created  for  each  unique 
memory  variable  name  or  field  name  used  in  a  program  or  at  the  dot 
prompt.  dBASE  IV  creates  only  one  runtime  symbol  for  each  field  or  mem¬ 
ory  variable  name,  no  matter  how  many  times  it  is  referenced.  The  number 
of  runtime  symbols  you  can  have  is  the  product  of  the  RTBLKSIZE  and 
RTMAXBLKS  settings  contained  in  the  Config.db  file.  RTBLKSIZE  is  the 
number  of  runtime  symbol  slots  each  block  may  contain,  and  RTMAXBLKS 
is  the  maximum  number  of  blocks  in  memory  that  may  be  allocated  for 
runtime  symbols.  The  default  setting  for  RTBLKSIZE  is  50,  and  the  default 
setting  for  RTMAXBLKS  is  10,  allowing  you  to  have  a  total  of  500  runtime 
symbols. 

As  with  memory  variable  blocks,  runtime  blocks  are  allocated  as  they  are 
needed.  When  one  block  is  full,  dBASE  IV  allocates  a  second  block.  Addi¬ 
tional  blocks  are  allocated  until  the  maximum  number  of  blocks,  which  is 
set  with  RTMAXBLKS,  is  reached.  Each  runtime  symbol  requires  17  bytes; 
when  the  first  block  is  allocated,  dBASE  reserves  enough  space  for  50  sym¬ 
bols,  which  is  850  bytes  of  memory. 

If  you  run  a  program  that  references  many  variables  or  field  names,  you  may 
need  to  allocate  more  memory  for  runtime  symbols.  If  you  have  not  pro¬ 
vided  for  a  sufficient  number  of  runtime  symbol  slots  in  the  Config.db  file, 
the  message  Exceeded  maximum  number  of  runtime  symbols  appears  dur¬ 
ing  program  execution,  and  you  should  increase  the  RTBLKSIZE  or 
RTMAXBLKS  settings. 

A  certain  amount  of  memory  overhead  is  used  for  displaying  memory  vari¬ 
ables.  Date  variables  require  8  bytes,  logical  variables  require  1  byte,  and 
numeric  variables  require  20  bytes.  As  the  information  for  character  vari¬ 
ables  is  already  stored  in  memory,  no  additional  overhead  is  required  to  dis¬ 
play  these  variables.  The  last  line  of  LIST/DISPLAY  MEMORY  shows  the  total 
amount  of  memory  overhead  used  to  hold  the  display  for  date,  logical,  and 
numeric  variables,  and  for  any  character  data  as  stored  in  memory.  264  bytes 
are  used  for  system  memory  variables,  so  264  bytes  will  always  show  on  the 
last  line,  even  if  you  do  not  create  any  other  variables.  For  each  variable  you 
create,  the  bytes  used  for  memvar  displays  A  CHARS  line  shows  the  addi¬ 
tional  overhead. 

You  may  also  decrease  the  Config.db  settings  for  MVBLKSIZE, 

MVMAXBLKS,  RTBLKSIZE,  and  RTMAXBLKS  if  you  need  additional 
memory  for  other  operations,  such  as  creating  windows  or  menus. 

Options 

TO  PRINTER  directs  command  output  to  the  printer,  and  TO  FILE  directs 
the  output  to  a  file  on  disk. 
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LIST/DISPLAY  MEMORY 


Examples 

To  illustrate,  the  character  string  'Hi  there'  has  been  stored  to  the  memory 
variable  Mgreetings;  the  Binary  Coded  Decimal  400.34  has  been  stored  to 
Mfixed;  a  logical  true  (.T.)  has  been  stored  to  Mtruth;  and  the  binary 
3.21E+"~06  has  been  stored  to  the  memory  variable  Mfloat. 

.  DISPLAY  fi&CRY 

User  Memory  Variables 
M3REE1TNGS  pub  C  'Hi  there'' 

MFLOAT  pxb  N  400.34  (40D.34aTrrmnTTTT)) 

NTRJTH  pub  L  .T. 

MFIXED  pcb  F  3210000  rovrm  tTTTTTTrTTnri 

4  user  irm/ars  defined 


See  Also 

DEFINE  MENU,  DEFINE  PAD,  DEFINE  POPUP,  DEFINE  WINDOW, 
PRIVATE,  PUBLIC,  RELEASE,  RESTORE,  SAVE,  STORE 

Chapter  5,  “System  Memory  Variables,”  includes  a  discussion  of  the  system 
variables  displayed  by  this  command. 

Chapter  6,  “Customizing  dBASE  IV,”  contains  information  on  Config.db 
settings,  including  MVBLKSIZE,  MVMAXBLKS,  RTBLKSIZE,  and 
RTMAXBLKS. 
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LIST/DISPLAY 

STATUS 


LIST/DISPLAY  STATUS  provides  information  about  the  current  dBASE  IV 
session. 

Syntax 

LIST/ DISPLAY  STATUS  [TO  PRINTER/TO  FILE  <  filename  >  ] 

Usage 

DISPLAY  STATUS  pauses  after  each  screen’s  display  and  prompts  you  to 
Press  any  key  to  continue...  LIST  STATUS  scrolls  without  pausing. 

For  each  open  database  file,  LIST/DISPLAY  STATUS  shows  the  following 
inform  ation: 

■  Current  work  area  number 

■  Database  name  with  drive,  path,  and  alias 

■  Open  index  filenames  (both  .ndx  and  .mdx  files),  index  key  expressions 
for  each  index  file  and  tag,  and  whether  the  index  is  UNIQUE  or 
DESCENDING 

■  Open  memo  filenames 

■  Filter  formulas 

■  Database  relations 

■  Format  files 

In  addition,  it  shows: 

■  File  search  path 

■  Default  disk  drive 

■  Print  destination 

■  Loaded  modules 

■  Currently  selected  work  area 

■  Left  margin  setting 

■  Currently  open  PROCEDURE  file 

■  Reprocess  count 

■  Refresh  count 

■  The  setting  for  DEVICE  (SCREEN,  PRINT,  or  FILE) 

■  Currency  symbol 
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LIST/DISPLAY  STATUS 


■  Delimiter  symbols 

■  Number  of  files  open 

■  ON  command  settings 

■  Current  settings  for  most  ON/OFF  SET  commands 

■  Function  key  assignments 


Options 

TO  PRINTER  directs  command  output  to  the  printer,  and  TO  FILE  directs 
the  output  to  a  file  on  disk. 


Special  Cases 

In  a  network  environment,  LIST/DISPLAY  STATUS  indicates  if  an  open  data¬ 
base  file  is  locked.  All  locked  records  in  each  work  area  are  listed. 

If  you  create  a  database  file  in  SQL  with  the  DISTINCT  keyword  of  the 
SELECT  statement,  the  file  will  be  designated  read-only  in  dBASE  IV. 
LIST/DISPLAY  STATUS  indicates  which  database  files  are  read-only;  you 
cannot  make  changes  to  these  files  from  within  dBASE  IV. 


See  Also 

ALIAS (),  DIR,  DISKSPACEQ,  FILEQ,  INDEX,  KEY(),  MDX(),  MEMORYQ, 
NDX(),  ORDERQ,  OS(),  PF  OGRAMQ,  SET,  TAG(),  VERSIONQ 
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LIST/DISPLAY 

STRUCTURE 


LIST/DISPLAY  STRUCTURE  displays  the  field  definitions  of  the  active  data¬ 
base  file. 


Syntax 

LIST/DISPLAY  STRUCTURE  [IN  <  alias  name>  ] 

[TO  PRINTER/TO  FILE  <  filename  >  ] 

Usage 

This  command  provides  the  following  information:  the  filename,  the  number 
of  records,  the  last  date  that  any  database  item  was  changed,  the  complete 
definition  of  each  of  the  fields,  which  fields  are  index  tags  in  the  production 
.mdx  file,  and  the  total  number  of  bytes  in  a  record. 

The  total  number  of  bytes  in  a  record  is  the  sum  of  all  the  field  widths  plus 
one  (the  extra  byte  stores  the  deleted  record  marker). 

If  the  number  of  fields  in  the  database  exceeds  16,  DISPLAY  STRUCTURE 
pauses  after  every  16  field  names  and  prompts  you  to  Press  any  key  to 
continue....  LIST  STRUCTURE  scrolls  without  pausing. 

If  SET  FIELDS  is  ON,  the  >  symbol  appears  beside  each  field  specified  with 
the  SET  FIELDS  TO  command. 


Options 

If  you  specify  IN  <  alias  name>  ,  the  structure  for  the  specified  work  area  is 
displayed. 

TO  PRINTER  directs  command  output  to  the  printer,  and  TO  FILE  directs 
the  output  to  a  file  on  disk. 


LANGUAGE  REFERENCE 


2-165 


JOBNAflE:  PAGE:  166  SESS:  10  Ued  flay  11  09:23:11  1988 


®tate/d  i  sk2/a  l  l  j  obz/CLS_manhat/GRP_manhat/JOB_man  l  angref /DIV_lrchap2d 

LIST/DISPLAY  STRUCTURE 


Example 

To  display  the  structure  of  the  Client  database: 

„  USE  Client 
.  LIST  STRUCTURE 


Structure  for  database:  C:\CGASEQ_IBfT.D6F 
Nurber  of  data  records:  8 
Date  of  Last  ipcbte  :  11/05/87 


Field 

Field  Name 

Type 

Width  Dec 

Index 

1 

CLIBIUD 

Character 

6 

Y 

2 

CUBIT 

Character 

30 

Y 

3 

LASTNAME 

Character 

15 

N 

4 

FIRSTNAfE 

Character 

15 

N 

5 

ADORESS 

Character 

30 

N 

6 

CITY 

Character 

20 

N 

7 

STATE 

Character 

2 

N 

8 

ZP 

Character 

10 

N 

9 

RCNE 

Character 

13 

N 

10 

CUBLHIST 

Memo 

10 

N 

**  Total  ** 

152 

See  Also 

COPY  STRUCTURE,  COPY  STRUCTURE  EXTENDED,  CREATE  or  MODIFY 
STRUCTURE,  CREATE  FROM 
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LIST/DISPLAY  USERS 


LIST/DISPLAY  USERS  identifies  the  workstations  currently  logged  in  to 
dBASE  IV  in  a  networking  environment. 


Syntax 

LIST/DISPLAy  USERS 

Usage 

This  command  reads  the  Login. db  file  in  the  current  directory  and  extracts 
the  network-assigned  names  of  the  workstations  currently  logged  in. 


Special  Cases 

Always  use  LIST/DISPLAY  USERS,  or  its  network  operating  system  equiva¬ 
lent,  to  determine  whether  anyone  is  using  dBASE  IV  before  it  is  uninstalled. 

If  two  or  more  users  log  in  with  the  same  workstation  name,  this  command 
displays  the  user  name  only  once.  For  example,  if  two  users  log  in  as 
WKSTN1,  LIST/DISPLAY  USERS  shows: 

Computer  Name 
>  WKSTN1 

even  if  they  both  logged  in  from  the  same  directory. 

See  Also 

LIST/DISPLAY  STATUS,  NETWORK() 


LANGUAGE  REFERENCE 


2-167 


JOBNAflE:  PAGE:  168  SESS:  9  Ued  Hay  11  09:23:11  1988 

State/di  sk2/al  l  j  obz/CLS_manhat/GRP_(nanhat/JOB_^an  I  angref  /D I V_ l  rchap2d 


LOAD 


LOAD  allows  you  to  load  binary  program  files  in  memory. 

Syntax 

LOAD  <  binary  filename> 


Usage 

LOAD  places  a  binary  (.bin)  file  in  memory  where  it  can  be  executed  with 
the  CALL  command  or  the  CALLQ  function. 


Programming  Notes 

dBASE  IV  treats  each  loaded  file  as  a  subroutine  or  program  module,  not  as 
an  external  program  file. 

A  maximum  of  16  files  may  reside  in  memory  at  one  time.  Each  can  be  up  to 
32,000  bytes  and  must  be  a  binary  file. 

Each  LOADed  module  must  have  a  unique  name.  The  default  extension  is 
.bin.  When  you  CALL  a  file,  omit  the  extension;  the  filename  itself  becomes 
the  module  name. 

If  you  LOAD  a  file  that  has  the  same  filename  but  a  different  extension  than 
one  already  LOADed,  the  new  one  replaces  the  first  one  in  memory. 

To  see  the  names  of  LOADed  modules,  issue  the  LIST/DISPLAY  STATUS 
command. 

dBASE  IV  does  not  check  the  integrity  of  the  files  you  LOAD.  Make  sure  that 
the  programs  are  in  binary  form  and  each  program  executes  properly. 

While  designing  the  assembly  language  program  from  which  the  binary  file  is 
made,  you  must  conform  to  the  following  specifications: 

■  You  must  originate  (ORG)  the  first  executable  instruction  at  an  offset  of 
zero. 

■  The  program  must  not  allocate  or  use  memory  over  and  above  its  actual 
size,  because  LOAD  uses  the  file  size  to  determine  how  much  memory  to 
allocate. 

■  The  program  must  not  lengthen  or  shorten  memory  variables  passed  as 
arguments  with  CALL  or  CALL(). 

■  Before  returning  control  to  dBASE  IV,  the  program  must  restore  both 
the  Code  Segment  (CS)  and  the  Stack  Segment  (SS)  Registers. 
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LOAD 


■  The  program  must  return  control  to  dBASE  IV  using  a  far  return  (RET 
FAR).  Most  commercial  programs  end  with  an  exit  call  rather  than  a  far 
return;  execute  these  with  the  RUN/!  command,  not  with  LOAD  and 
CALL. 

To  prepare  an  assembly  language  program  written  in  8086/8088  assembler 
for  LOADing  by  dBASE  IV,  use  the  DOS  macro  assembler  and  the  following 
DOS  program  commands: 

■  To  assemble  programs  and  create  an  object  (.obj)  file: 

MASM  <  source  >  <  target>  NULL  NULL 

■  To  link  OBJ  files  and  create  an  executable  (.exe)  file: 

LINK  <  target  >  NULL  NULL 

■  To  create  a  binary  (.bin)  file  from  an  executable  file: 

EXE2BIN  <  target  > 


Example 

Assuming  that  the  default  drive  is  C,  execute  the  binary  file  Getdrive.bin  and 
return  the  drive  into  the  memory  variable  M_drive: 

..  LfAD  Getdrh * 

.  =  *  * 

.  CALL  Getdriie  WITH  H_dri\* 

*  ?  'The  arrent  ctiie  is  ftjHve 
The  current  drive  is  C 


See  Also 

CALL,  CALLQ,  LIST/ DISPLAY  STATUS,  RELEASE,  RUN 
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LOCATE 


LOCATE  searches  the  active  database  file  for  a  record  that  matches  a  speci¬ 
fied  condition. 


Syntax 

LOCATE  FOR  <  condition  >  [<  scope  >  ]  [WHILE  <  condition  >  ] 


Usage 

LOCATE  performs  a  sequential  search  of  a  database  file  and  tests  each  record 
for  a  match  to  the  FOR  condition.  The  condition  will  evaluate  to  true  (,T.)  or 
false  (.F.)  for  each  record.  If  the  condition  evaluates  to  true,  a  match  is 
found,  and  LOCATE  positions  the  record  pointer  on  this  first  matching 
record. 

LOCATE  does  not  require  an  indexed  database  file.  FIND  and  SEEK,  which 
operate  on  indexed  files,  are  generally  much  faster. 

You  must  provide  a  logical  condition  in  the  FOR  clause,  such  as  LOCATE 
FOR  Lastname  =  'Goreman",  or  LOCATE  FOR  .T. 

To  find  the  next  occurrence  of  the  specified  condition,  use  the  CONTINUE 
command.  Even  if  you  issue  several  LOCATE  commands  against  the  same 
database  file,  CONTINUE  always  continues  the  search  of  the  most  recent 
LOCATE. 

LOCATE  and  CONTINUE  are  specific  to  the  work  area  in  which  they  are 
issued.  You  can  have  a  different  LOCATE  in  each  work  area.  If  you  issue  a 
LOCATE,  then  select  another  work  area,  and  later  return  to  the  first  work 
area  and  issue  a  CONTINUE  command,  the  search  will  pick  up  where  the 
previous  LOCATE  in  that  work  area  left  off. 


Record  Pointer 

Unless  otherwise  restricted  by  the  scope  or  a  WHILE  clause,  LOCATE  reposi¬ 
tions  the  record  pointer  to  the  beginning  of  the  database  file  and  starts  the 
search  with  the  first  record. 

The  NEXT  <  n>  scope  option  limits  the  search  to  the  specified  number  of 
records.  The  NEXT  <  n>  and  REST  scope  options  do  not  reposition  the 
record  pointer  at  the  beginning  of  the  database  file;  the  search  starts  at  the 
current  record. 

If  a  match  is  found,  the  record  pointer  moves  to  that  record.  If  SET  TALK  is 
ON,  dBASE  IV  shows  the  record  number.  FOUND()  returns  T. 
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LOCATE 


If  no  match  is  found,  the  record  pointer  moves  to  the  end  of  the  filyfEOFQ 
is  .T.),  or  the  end  of  the  scope  if  you  specified  one,  and  the  message “End  of 
LOCATE  scope  appears.  FOUND()  returns  .F. 


Examples 


To  locate  the  first  record  in  the  Transact  database  file  that  contains  the 
Client.,  id  L00001: 

.  USE  Transact 

.  LOCATE  FOR  CL  ientJd  =  " UJOCD1 w 
Record  =  5 


To  locate  each  record  that  contains  a  Client. id  of  C00001  and  has  not  been 
invoiced: 


.  LOCATE  FOR  CL  ientJd  =  ’CdWT  .AFD.  JOT.  Invoiced 
Record  =  11 

.  DISPLAY 

Record#  OIBHUD  CRDERJD  DATEJRANS  INDUCED  TOTALBILL 

11  aUDI  87-115  04/01/87  .F.  165.00 

.  CONTINUE 
End  of  LOCATE  scope 
.  ?  EDFO 
.T. 

.  ?  FOUDO 
.F. 


See  Also 

CONTINUE,  FIND,  FOUNDQ,  SEEK 


: 

1 

I 
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LOGOUT 


LOGOUT  logs  out  the  current  user  and  sets  up  a  new  log-in  screen. 


Syntax 

LOGOUT 

Usage 

The  LOGOUT  command  enables  you  to  control  user  sign-in  and  sign-out 
procedures.  The  command  forces  a  logout  and  prompts  for  a  login. 

When  the  command  is  processed,  the  workstation  screen  clears  and  a  log-in 
screen  appears.  The  user  can  then  enter  a  group  name,  log-in  name,  and 
password.  The  PROTECT  command  establishes  log-in  verification  functions 
and  sets  the  user  access  level. 

LOGOUT  closes  all  open  database  files,  their  associated  files,  and  program 
files. 

Special  Cases 

If  PROTECT  has  not  been  used,  no  Dbsystem.db  file  is  created,  and  LOGOUT 
returns  the  user  to  the  dot  prompt  instead  of  to  the  log-in  screen. 


See  Also 

PROTECT 
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MODIFY 

COMMAND/FILE 


MODIFY  COMMAND/FILE  is  the  dBASE  IV  full-screen  text  editor.  Its  func¬ 
tion  is  to  create  and  edit  dBASE  program  and  format  files  and  to  edit  memo 
fields.  You  can  also  use  it  to  create  or  edit  any  standard  ASCII  text  file 


Syntax 

MODIFY  COMMAND/ FILE  <  filename*  [WINDOW  <  window  name*  ] 


Defaults 

If  you  do  not  specify  the  drive,  directory,  or  file  extension  as  part  of  the  file¬ 
name  for  MODIFY  COMMAND,  the  default  drive  and  directory  and  the  .prg 
extension  are  used. 

MODIFY  FILE,  the  alternative  syntax  for  the  dBASE  IV  text  editor,  does  not 
provide  a  default  extension.  If  you  do  not  specify  an  extension  when  you  cre¬ 
ate  a  file  with  MODIFY  FILE,  none  is  provided. 


Usage 

MODIFY  COMMAND/FILE  calls  up  dBASE  IV-s  full-screen  text  editor  to 
create  or  edit  program  and  format  files.  You  can  call  it  from  the  dot  prompt 
or  the  dBASE  IV  Control  Center,  when  you  attempt  to  edit  a  program  or  pro¬ 
cedure  file,  or  a  memo  Held. 

MODIFY  COMMAND  operates  in  the  active  window.  You  can  also  assign  it  to 
an  alternate  window,  using  the  WINDOW  option.  If  the  <  window  name> 
does  not  exist,  dBASE  IV  displays  the  error  message  Window  name  not 
found. 

The  maximum  file  size  MODIFY  COMMAND/FILE  can  handle  is  usually 
limited  by  the  amount  of  available  disk  space.  It  allows  line  lengths  of  up  to 
1,024  characters  and  32,000  word-wrapped  lines.  Therefore,  the  maximum 
possible  file  size  would  be  32,000  times  1,024  characters  or  32,768,000  bytes. 

You  can  use  an  external  word  processor  instead  of  the  dBASE  IV  text  editor, 
if  you  set  it  up  in  the  Config.db  file  on  installation.  Refer  to  the  installation 
instructions  in  Chapter  6  for  the  procedure  to  do  this.  It  is  to  your  advan¬ 
tage,  however,  to  use  the  dBASE  editor  when  working  with  dBASE  IV  files. 
When  you  edit  a  program  file  with  MODIFY  COMMAND/FILE  that  has  an 
associated  object  file  (  dbo),  the  object  file  is  deleted  after  the  edited  file  is 
saved.  dBASE  IV  generates  a  new  object  file  the  first  time  the  edited  pro¬ 
gram  is  run.  An  external  editor  will  leave  the  old  object  file,  which  may 
cause  an  error  with  your  modified  program. 
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MODIFY  COMMAND/FILE 


When  you  issue  the  MODIFY  COMMAND/FILE  command,  dBASE  IV 
searches  for  the  specified  file.  If  the  file  exists,  it  is  called  up  for  editing.  If 
the  file  is  not  found,  a  new  file  is  created.  Use  MODIFY  FILE  to  edit  an 
ASCII  file  by  specifying  the  extension.  Each  time  you  edit  a  file,  the  previous 
version  is  saved  as  a  backup  file  with  the  .bak  extension. 

The  menus  you  can  use  for  editing  appear  at  the  top  of  your  screen.  A  com¬ 
plete  list  of  the  editing  keys  you  can  use  is  given  in  Quick  Reference.  More 
information  on  the  use  of  the  Layout,  Words,  and  Print  menus  can  be  found 
in  Using  the  Menu  System. 

You  can  also  get  a  printout  of  a  file  created  by  MODIFY  COMMAND/FILE  by 
entering: 

.  TYPE  <filename>  TV  PRINT 

Special  Case 

During  multi-user  operations,  dBASE  IV  automatically  locks  the  record  you 
are  editing,  so  that  simultaneous  editing  of  a  memo  field  is  not  possible. 
Also,  in  multi-user  operations,  CREATE  and  UPDATE  privileges  must  be  in 
effect  before  you  can  MODIFY  a  file. 


See  Also 

COMPILE,  CREATE,  DO,  NOTE/V&&,  RENAME,  TYPE,  UPDATE 
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MODIFY  Commands 


TheiCommands  are  synonymous  with  the  corresponding  CREATE  commands. 
See' the  CREATE  command  for  the  proper  syntax  and  usage  of  these 
commands. 


A  v 


MODIFY  APPLICATION 
MODIFY  LABEL 
MODIFY  REPORT 
MODIFY  SCREEN 
MODIFY  STRUCTURE 
MODIFY  QUERY/ VIEW 


C/1  a  /oj) 
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MOVE  WINDOW 


The  MOVE  WINDOW  command  moves  a  window  to  a  new  location  on  the 
screen. 


Syntax 

MOVE  WINDOW  <  window  name>  TO  <  row  >  <  column  >  /BY 
<  delta  row  >  , <  delta  column  > 


Usage 

The  syntax  shown  combines  two  different  ways  of  moving  a  window.  You  can 
give  the  new  coordinates  for  the  window,  or  you  can  give  the  change  you 
want  in  the  placement  of  the  window,  relative  to  its  current  position. 

Once  you  move  a  window,  the  coordinates  of  the  new  location  are  associated 
with  that  window  name.  If  you  want  the  window  back  at  its  original  location, 
you  must  issue  another  MOVE  WINDOW  command  that  contains  the  original 
row  and  column  parameters. 

If  the  window  does  not  fit  on  the  screen  at  the  new  location,  an  error  mes¬ 
sage  appears  and  the  MOVE  WINDOW  command  does  not  take  effect. 


Examples 

To  move  a  window  called  W1  to  the  right  by  2  columns  and  down  by  5  lines: 

.  KNE  WINDCU  VI  Bf  5,2 

To  move  the  window  W1  to  new  coordinates: 

.  /W  UNDCV  VJ  TO  10^ 

See  Also 

ACTIVATE  WINDOW,  DEACTIVATE  WINDOW,  DEFINE  WINDOW,  RESTORE 
WINDOW,  SAVE  WINDOW 
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NOTE/V&& 


NOTE,  an  asterisk  (*),  or  double  ampersand  (&&)  characters  indicate 
comment  lines  in  a  program  (.prg)  ■ 

Syntax 

NOTE/*  <  text > 
and 

[<  command>  ]  &&<  text> 


NOTE/*/&&  inserts  comments  into  program  files  for  documentation  and 
explanatory  purposes.  Use  NOTE  and  *  at  the  beginning  of  a  line  within  a 
program.  Use  &&  to  insert  comments  on  the  same  line  with  a  command  in  a 
program.  You  may  use  the  &&  either  after  the  command  and  before  the 
comment,  or  at  the  beginning  of  a  line. 

If  a  &&  line  ends  with  a  semicolon,  dBASE  IV  reads  the  next  line  as  part  of 
the  comment  fine.  You  cannot  use  a  semicolon  with  NOTE/*.  Each  fine  must 
begin  with  either  NOTE  or  *. 


Examples 

This  example  shows  how  you  might  use  NOTE  or  *: 

in  savt  wit 

\^\  \  a  «  S(-pcc  ze 
<  ^  " 

This  example  uses  &&  to  put  a  comment  on  a  program  fine: 

M tmjar  =  12  8&  initializes  runeric  mawr 

See  Also 

MODIFY  COMMAND/ FILE,  PROCEDURE 


NOTE  This  is  a  sinple  locp 
-''suss  t  to  (ht 


<STCRE  T  tD  Qit 
•JO  WHILE  Cht  <  OT 
^  STORE  Cht  +  1  TO 


*lkxo 


TO^Sit 
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ON  ERROR/ 

ESCAPE/KEY 


ON  ERROR/ ESCAPE/ KEY  branches  the  execution  of  a  program  if  one  of  the 
three  listed  conditions  occurs. 


Syntax 

ON  ERROR/ESCAPE  [<  command  >  ] 

ON  KEY  [  <  key  label  name  >  ]  [  <  com  m  and  >  ] 


Usage 

The  ON  command  sets  a  trap  that  waits  for  the  specified  condition  to  occur. 
These  conditions  are  a  dBASE  IV  error,  pressing  the  Esc  key,  or  pressing 
either  a  key  designated  in  <  key  label  name  >  or  any  key  if  no  key  label  is 
designated.  dBASE  IV  errors  include,  for  example,  syntax  errors  and  evalua¬ 
tion  errors.  You  must  specify  a  command  to  use  these  ON  conditions.  The 
ON  condition  remains  in  effect  until  you  explicitly  remove  it  by  entering  ON 
ERROR/ ESCAPE/ KEY  with  no  argument,  or  until  you  leave  dBASE  IV. 

Note  that  ON  ESCAPE  does  not  work  when  SET  ESCAPE  is  OFF. 


Programming  Notes 

dBASE  IV  responds  to  the  ON  options  in  the  following  order  of  precedence: 

ON  ERROR  =  A  dBASE  IV  error  occurred 

ON  ESCAPE  =  The  Esc  key  is  pressed 

ON  KEY  =  Any  key  or  label  is  pressed 


If,  for  example,  ON  KEY  and  ON  ESCAPE  are  in  effect  at  the  same  time, 
pressing  the  Esc  key  executes  the  ON  ESCAPE  command.  It  does  not  branch 
to  the  ON  KEY  command  line. 

If  only  ON  KEY  is  in  effect  and  SET  ESCAPE  is  OFF,  pressing  the  Esc  key 
activates  the  command  specified  in  the  ON  KEY  command  line. 

If  the  ON  KEY  command  is  in  effect,  and  you  press  any  key  other  than  Esc, 
ON  KEY  is  executed  after  the  current  command  is  completed.  For  instance, 
pressing  a  key  while  INDEXing  a  file  will  not  interrupt  the  index  procedure. 
Unless  the  program  removes  the  stored  key,  however,  the  command  you 
specify  on  the  ON  KEY  command  line  will  execute  repeatedly. 
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ON  ERROR/ESCAPE/KEY 


You  must  clear  the  type-ahead  buffer  before  using  ON  KEY.  You  can  do  this 
in  either  of  two  ways,  with  INKEY()  or  ON  KEY  WAIT  TO.  When  you  use  the 
INKEY()  function,  and  store  the  INKEY()  value  to  a  memory  variable,  you 
are  also  removing  the  keystroke  from  the  type-ahead  buffer 

ON  ERROR  does  not  respond  to  errors  at  the  operating  system  level,  such  as 
a  drive  or  printer  not  being  accessible.  It  responds  only  to  dBASE  IV  errors, 
such  as  a  syntax  error  or  an  evaluation  error.  Also,  returning  from  an  ON 
ERROR  <  command  >  will  not  re-evaluate  an  IF  or  DO  WHILE  condition  in 
the  program  in  which  the  error  occurred. 


Examples 


The  examples  below  assume  that  a  procedure  file  containing  IF_err  and 
Stop  is  already  open. 

To  activate  the  ON  ERROR  option  when  a  dBASE  IV  error  occurs,  type  the 
following: 

.  CN  ERROR  DO  ILerr 


Then,  if  dBASE  IV  encounters  an  error,  it  branches  to: 


PTOCEDLRE  If_err 
<If_err.prg  ccmrand  list> 


'*  Tim  off  the  cn  error  flag  if  you 
*  dcn't  wart  to  trap  additional  errors. 

CN  ERROR 
RETLRJ 

To  set  up  the  ON  KEY  option  to  execute  a  DO  <  program  >  command  that 
halts  printing  and  branches  to  a  procedure  named  Stop,  enter: 

.  CN  KEY  DO  Step 

Afterward,  if  you  press  any  key,  the  program  branches  to  the  Stop  procedure. 
The  following  procedure  prompts  you  to  press  the  letter  A  if  you  want  to 
stop  printing.  Pressing  any  other  key  causes  printing  to  resume. 
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ON  ERROR/ESCAPE/KEY 


PROCEDURE  Step 

*  First  clear  the  key  that  triggered  CN  KEY 

*  fran  the  type-ahead  buffer  with  INQEYO. 
i  =  BttEYO 

WAIT  "  Press  A  to  Abort  printing,  "  +; 

"any  other  key  to  ant-hue1'  TO  choice 
IF  LFFER  (choice)  =  "PC 
RETIFN  TO  MASTER 
BOIF 
RETURg 


See  Also 

INKEYQ,  PROCEDURE,  READKEY(),  RETURN,  SET  ESCAPE,  SET/PROCE- 
DURE,  UPPER(),  WAIT  ^ 


z 
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ON  PAD  associates  a  pop-up  menu  with  a  pad  of  a  given  bar  menu. 

Syntax 

ON  PAD  <  pad  name>  OF  <  menu  name>  [ACTIVATE  POPUP 
<  popup  name>  ] 


The  pop-up  menu  named  with  the  ON  PAD  command  is  activated  whenever 
the  cursor  is  on  the  pad  of  the  specified  bar  menu. 

If  you  do  not  use  the  ACTIVATE  POPUP  option  with  the  ON  PAD  command, 
the  prompt  pad  is  disabled. 

By  using  the  ACTIVATE  POPUP  option,  you  can  have  both  bar  menus  and 
pop-up  menus  active  on  the  screen  at  the  same  time.  As  you  use  the  -*  and 
—  keys  to  move  within  a  bar  menu,  you  activate  different  pop-up  menus. 
You  can  use  the  T  and  the  |  keys  to  move  between  the  BARS  of  the  pop-up 
menus. 

You  cannot  use  this  command  if  you  have  already  used  the  ON  SELECTION 
PAD  command  to  associate  a  prompt  or  a  program  with  a  pad. 


Example 

To  activate  the  pop-up  menus  for  the  View,  Goto  and  Print  choices  of  the 
Main  bar  menu  when  the  cursor  is  moved  onto  the  appropriate  pad: 


.  CN  PAD  Vim  Of  /bin  ACTIVATE  PORP  Vimjxp 
.  CN  PAD  Goto  OF  /bin  ACTIVATE  POFLP  Gotojxp 
.  CN  PAD  Print  OF  /bin  ACTIVATE  PCRP  PrintL_pcp 


See  Also 

DEFINE  MENU,  DEFINE  PAD,  DEFINE  POPUP,  ON  SELECTION  PAD, 
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ON  PAGE 


ON  PAGE  is  the  dBASE  IV  command  for  handling  page  breaks  with  footers 
and  headers  while  printing  a  report. 

Syntax 

ON  PAGE  [AT  LINE  <  expN  >  <  command  >  ] 

Usage 

ON  PAGE  executes  the  specified  command  when  dBASE  IV  encounters  the 
line  number  designated  in  the  AT  LINE  clause.  dBASE  IV  keeps  track  of  the 
line  number  by  updating  the  _plineno  system  variable  (see  Chapter  5, 
“System  Memory  Variables”)  when  a  PRINTJOB  is  active. 

ON  PAGE  permits  a  program  to  execute  a  valid  command,  such  as  a  footer 
and  header  procedure,  at  the  end  of  each  page.  The  command  executed  by 
ON  PAGE  is  known  as  the  page  handler. 

ON  PAGE  with  no  argument  disables  the  page  handler. 

Use  the  following  formula  to  determine  the  value  of  <  expN >  for  the 
AT  LINE  clause: 

<  expN  >  =  page  lengthQbottom  margin  (^footer  height 

The  page  length  is  the  value  of  the  _plength  system  variable.  The  footer 
height  is  the  number  of  lines  in  the  footer,  as  defined  by  the  footer  proce¬ 
dure  (see  “Example,”  below).  The  bottom  margin  is  the  number  of  blank 
lines  below  the  last  line  of  the  footer.  You  don’t  define  the  bottom  margin 
explicitly  —  it  derives  from  the  other  two  values. 

ON  PAGE  works  only  in  printjobs  (defined  by  PRINTJOB  and  END 
PRINTJOB).  Place  the  ON  PAGE  command  before  the  PRINTJOB  command 
in  your  code. 

dBASE  IV  keeps  track  of  the  number  of  lines  in  the  header,  and  adjusts  the 
lines  of  text  on  that  page  accordingly.  You  must  ensure,  however,  that  the 
number  of  lines  in  the  footer  don’t  exceed  the  lines  remaining  on  the  page. 
If  they  do,  the  footer  will  run  onto  the  top  of  the  next  page. 

If  you  have  used  the  report  generator  to  create  a  report  with  headers  and 
footers,  the  REEORT  FORM  command  activates  the  page  handler  automati¬ 
cally  as  it  prints  the  report.  You  can  also  provide  a  page  handler  for  other 
commands  that  produce  printed  output,  such  as  DISPLAY  and  LIST  (see 
“Example”). 
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Example 

Assuming  you  want  six -line  top  and  bottom  margins,  a  program  file  to  LIST 
an  inventory  might  look  like  this: 


8&  Print  first  page  header. 
8&  LIST  irwentory. 

8&  Print  Last  page  footer. 

8&  Disable  the  page  handler. 


*  Name...:  Invntry.prg 
CN  PAGE  AT  Uf€  60  DO  FbgeJrk 
\SET  TALK  OFF 
SET  PRINT  CN 
DO  Header 
LIST 

DO  Footer 
SET  PRINT  OFF 
CN  PAGE 
SET  TALK  CN 
RETIIN 

*  ECP:  IrMitry.prg 
PROCEDLRE  Header 

_prow  =  3  y  8&  Print  the  heading  on  line  three. 

V.  "CLrrent  Invanto^  STYLE  B,  DATEO  AT  70 

_prow  =  7  8&  Start  LISTing  cn  the  seventh  line. 

RETURN 

*  ECP:  Header 


PROCEDLRE  Footer 

_prcw  =  65  8&  Print  the  footer  on  line  63. 

??  "  CCNFIDENTIAL  -  Do  not  distribute!" 

??  "Ffege  "  AT  70,  STR(_pagero,4,0) 

EJECT  S&  Start  a  new  page. 

RETURN 

*  ECP:  Footer 
FROCEDLRE  PageJrk 

DO  Footer  8&  Print  the  footer. 

DO  Header  8&  Print  the  header. 

RETLRJ 

*  ECP:  Rag*_brk 


See  Also 

PRINTJOB,  PROCEDURE,  REPORT  FORM,  RETURN,  SET  PRINTER, 
_plength,  _plineno 
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ON  READERROR 


Use  ON  READERROR  for  error  trapping  and  recovery  during  full-screen 
operations. 


Syntax 

ON  READERROR  [<  comm  an  d  >  ] 

Usage 

Use  ON  READERROR  to  activate  a  command,  program,  or  procedure  after 
checking  for  an  error  condition.  The  errors  trapped  by  ON  READERROR  are 
invalid  dates,  a  RANGE  specification  during  data  entry  that  is  out  of  range, 
or  an  unmet  VALID  <  condition  >  .  When  your  program  encounters  these,  it 
will  execute  the  command  or  program  specified  in  the  ON  READERROR 
command  line.  Specifying  ON  READERROR  without  a  command  disables 
the  program’s  ability  to  trap  errors. 


Tip 

This  command  will  usually  be  a  DO  <  command  file>  to  recover  from  the 
error  or  send  a  help  message  to  the  screen.  You  can  prompt  for  the  correct 
input  by  having  the  program  specify  valid  entries. 


See  Also 

@,  APPEND,  CHANGE,  EDIT,  INSERT,  ON  ERROR,  READ 
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ON  SELECTION  PAD 


ON  SELECTION  PAD  associates  a  command,  procedure,  or  program  with  a 
bar  menu  pad,  so  that  selecting  that  bar  menu  pad  executes  the  specified 
command,  procedure,  or  program. 


■ 


Syntax 

ON  SELECTION  PAD  <  pad  name>  OF  <  menu  name>  [<  command  >  ] 

Usage 

When  you  select  any  pad  from  an  active  menu,  ON  SELECTION  PAD 
executes  what  has  been  specified  in  the  <  comm  and  >  clause.  The 

<  command  >  clause  can  contain  a  dBASE  IV  command  or  a  DO 

<  program  name/procedure  name>  instruction.  Aprocedure  associated 
with  ON  SELECTION  PAD  can  use  functions  such  as  MENU()  or  PAD()  to 
determine  the  active  menu  name  and  the  last  selected  pad,  and  to  perform 
appropriate  actions. 

During  program  execution,  the  active  menu  is  deactivated.  After  the  com¬ 
mand,  procedure,  or  program  is  finished,  the  menu  is  activated  again  and 
you  can  make  another  menu  selection. 

If  you  use  the  ON  SELECTION  PAD  command  without  a  command  or  pro¬ 
gram,  the  named  pad  is  deactivated. 

Example 

In  the  sample  files,  the  Exit_pop  menu  is  activated  when  •*-*■  is  pressed  on 
the  Exit  pad  of  the  Main  bar  menu.  This  is  accomplished  with  the  command: 

.  CN  SELECTION  fW  Exit  OF  fibin  ACTIVATE  PCRP 
Exit_pcp 


See  Also 

DEFINE  MENU,  DEFINE  PAD,  MENUQ,  ON  PAD,  PADQ,  PROMPT() 
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ON  SELECTION 
POPUP 


ON  SELECTION  POPUP  specifies  the  command  or  procedure  that  executes 
when  a  pop-up  menu  selection  is  made. 


Syntax 

ON  SELECTION  POPUP  <  popup  name>  /ALL  (<  command  >  ] 

Usage 

Use  this  command  to  associate  any  one  of  the  prompts  of  the  specified  pop¬ 
up  menu  with  a  dBASE  IV  command  or  procedure.  Use  the  DO  command  to 
execute  a  program  or  a  procedure. 

If  you  use  ON  SELECTION  POPUP  without  specifying  a  command,  the  active 
popup  is  deactivated.  If  you  use  ALL  for  the  pop-up  name,  this  com  mand 
applies  to  all  of  the  popups. 

If  you  used  the  PROMPT  FIELD  <  fieldname  >  option  of  the  DEFINE 
POPUP  command,  ON  SELECTION  POPUP  positions  the  record  pointer  to 
the  record  that  contains  the  field  that  you  selected. 

User-defined  menu  commands  should  be  issued  in  the  following  order: 

1.  DEFINE  POPUPS. 

2.  ON  SELECTION  POPUP. 

3.  ACTIVATE  POPUP. 

When  you  select  any  one  o  the  prompts  from  the  pop-up  menu  by  pressing 
the  menu  is  deactivated  while  the  command  or  the  procedure  associated 
with  ON  SELECTION  POPUP  executes. 


Examples 

When  ♦♦  is  pressed  on  the  Exit_pop  menu,  the  PROCEDURE  Exit_pro 
executes: 

.  CN  SELECTION  KFLP  Exitjxp  DO  Exitjro 

Typically,  a  procedure  executed  from  a  menu  will  contain  both  a  DO  CASE 
structure  to  evaluate  the  user’s  selection  and  what  operation  to  perform  in 
response  to  the  selection.  The  POPUPQ,  PROMPTQ  or  BAR()  functions  can 
be  used  to  identify  the  user’s  selection. 
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ON  SELECTION  POPUP 


Here  is  a  sample  procedure  for  the  View_pop  menu: 

DO  CASE 

CASE  BAR  0=1 
APPBD  EUNC 
EDIT  tEXl  1 
CASE  BARO  =2 
BIT  hEXT  1 
CASE  BARO  =4 
DELETE 
BDCASE 
RETURN 


See  Also 

BAR(),  DEFINE  BAR,  DEFINE  POPUP,  POPUP(),  PROMPT() 
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PACK 


PACK  removes  records  that  are  marked  for  deletion  from  the  active  database 
file. 

Syntax 

PACK 

Usage 

All  open  index  files  are  automatically  REINDEXed. 

After  you  execute  a  PACK  command,  the  disk  space  used  by  the  deleted 
records  is  reclaimed  when  the  file  is  closed.  Make  certain,  however,  that  you 
have  enough  disk  space  to  hold  two  copies  of  the  database  file  during  the 
pack  operation. 

Note  that  the  DIR  and  LIST/DISPLAV  FILES  commands  do  not  accurately 
reflect  increases  or  decreases  in  file  sizes  until  the  file  is  closed. 

See  Also 

COPY,  DELETE,  DELETEDQ,  DIR,  RECALL,  REINDEX,  ZAP 
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PARAMETERS 


PARAMETERS  assigns  local  variable  names  to  data  items  passed  from 
a  calling  program .  This  command  receives  variables  passed  using  the 
[DQ/fcom  m  andj  <  filename  >  WITH  <  parameter  list>  . 

Syntax 

PARAMETERS  <  parameter  list > 

Usage 

When  included  in  a  dBASE  program  file,  PARAMETERS  must  be  the  first 
executable  command.  In  a  procedure  file,  PROCEDURE  <  filename  >  is  the 
first  command,  followed  by  the  PARAMETERS  command.  The  parameters 
you  pass  can  be  any  legitimate  expressions.  The  parameter  list  assigns  local 
variable  names  to  receive  parameters  from  the  sending  program’s  parameter 
list.  The  local  variables  created  by  specifying  PARAMETERS  are  discarded 
when  control  is  returned  to  the  calling  program.  The  parameter  list  must 
contain  the  same  number  of  items  as  in  the  calling  program.  You  may  pass 
up  to  50  parameters  from  the  calling  program. 

If  the  parameter  being  passed  is  a  memory  variable,  its  value  may  be 
changed.  The  change  is  transferred  to  the  variable  in  the  calling  program.  If 
the  parameter  being  passed  is  an  expression,  the  value  of  that  expression  is 
stored  to  a  memory  variable  in  the  receiving  program. 


Examples 

The  following  command  file  calculates  the  area  for  a  given  length  and  width: 

♦The  ccnrard  file  Areacalc.prg 
PAfWETERS  Length,  Width,  A 
*  A  correspcnds  to  area 
A  =  Length  *  Width 
RETURN 

*H)F:  Areacalc.prg 
To  execute  this  command  file: 


.  area  =  0_ 

0] 

.  DO  Areacalc  WITH  6,  4,  area 
J  24.0D 

.  ?  area 

24 


See  Also 

DO,  PRIVATE,  PROCEDURE,  PUBLIC,  SET  PROCEDURE,  STORE 
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PLAY  MACRO 


This  command  executes  macros  created  from  the  Control  Center. 


Syntax 

PLAY  MACRO  <  macro  name> 


A  macro  is  a  series  of  keystrokes  that  you  record  to  a  file.  You  give  each 
macro  a  unique  identifier,  and  you  can  execute  the  keystrokes  at  any  time  by 
invoking  the  identifier. 

When  you  create  a  macro,  you  can  identify  it  with  a  macro  key  and  a  macro 
name. 

The  macro  key  may  be  a/t-fi  through  a£F-F9,  or  it  may  be  A^T-FIO 
followed  by  a  letter  from  A  to  Z.  Therefore,  you  can  assign  up  to  35  keys,  and 
create  up  to  35  unique  macros.  The  macro  name  may  be  up  to  10  characters 
long,  and  must  not  include  spaces. 

The  macros  that  you  create  and  save  can  be  played  back  in  three  ways: 

■  By  typing  S^BFT-FIO,  then  choosing  Play  from  the  menu. 

■  By  typing  the  macro  key  from  the  keyboard.  You  may  press  AJ5F-F1 
through  A/S'-F9,  or  AJu-FlO  followed  by  a  letter  from  A  through  Z(case 
does  not  matter). 

■  By  using  the  PLAY  MACRO  command  with  the  macro  name. 

As  PLAY  MACRO  allows  you  to  execute  the  macro  by  name,  you  can  include 
this  command  in  program  files  to  execute  a  macro  without  prompting  the 
user  to  type  the  macro  key. 


See  Also 

RESTORE  MACROS,  SAVE  MACROS 
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PRINTJOB/ 

ENDPRINTJOB 


PRINTJOB/ENDPRINTJOB  are  structured  programming  commands  that 
control  a  printjob. 


Syntax 

PRINTJOB 

<  commands  > 
ENDPRINTJOB 


Usage 

Use  PRINTJOB  to  activate  printjob-related  settings  and  ON  PAGE  for  the 
duration  of  a  printing  task.  You  define  the  actual  print  settings  with  system 
memory  variables,  which  you  place  before  and  after  the  PRINTJOB 
com  mand. 

Asystem  memory  variable  is  a  memory  variable  initialized  by  dBASE  IV 
which  you  can  modify.  See  Chapter  5,  “System  Memory  Variables,”  for  a 
description  of  each. 

PRINTJOB  causes  dBASE  IV  to: 

■  Send  the  starting  print  codes  defined  by  the  _pscodes  system  variable 

■  Eject  the  paper  if  _peject  is  set  to  either  'BEFORE'  or  'BOTH' 

■  Initialize  _pcolno  to  0 

■  Activate  _plineno  and  ON  PAGE 
ENDPRINTJOB  causes  dBASE  IV  to: 

■  Send  the  ending  print  codes  defined  by  the  _pecodes  system  variable 

■  Eject  the  paper  if  _peject  is  set  to  either  'AFTER'  or  'BOTH' 

■  Loop  back  to  PRINTJOB  the  number  of  times  defined  by  _pcopies. 

■  Deactivate  _plineno  and  ON  PAGE 

In  your  code,  place  the  definitions  for  these  system  variables  before  the 
PRINTJOB  command.  If  necessary,  redefine  any  system  variables  used  in 
your  code  after  ENDPRINTJOB. 

You  can  define  other  system  variables,  as  well,  for  a  specific  printjob.  If  you 
want  a  feature  to  apply  to  an  entire  printjob,  define  the  variable  before  the 
PRINTJOB  command.  For  example,  you  might  want  to  pause  the  printing 
after  each  page  or  define  a  specific  page  offset. 
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PRINTJOB/ENDPRINTJOB 


On  the  other  hand,  if  you  want  to  change  a  print  setting,  such  as  .alignment, 
during  a  printjob,  define  the  variable  between  the  PRINTJOB  and 
ENDPRINTJOB  commands. 

You  can  use  PRINTJOB  and  ENDPRINTJOB  only  within  a  program,  and  you 
cannot  nest  printjobs. 

Example 

The  following  example  sets  up  a  custom  printjob  using  the  Client. dbf  data¬ 
base  example  file. 


*  Customer. prg 
USE  Client 
_peject=*' AFTER' 

SET  PRINT  CN 
PRINTJC8 

CN  PAGE  AT  LINE  _plength-1  DO  Rage&ic 
DO  WHILE  .NOT.  EDFO 

??  Client->ClientJd  AT  0,  Cli«nt->Client  AT  8 
? 

kip 

BDOO 

BUPRINTJC8 
SET  PRINT  OFF 
RETUN 

*  ECP:  Customer. prg 

PROCEDURE  PageBric 
EJECT 

V.  DATEO  AT  1,  "Rsge:"  AT  67,  jageno  PICTIRE  C999D  AT  73 

7 

7 

RETURN 

*  ECP:  PageBrk 
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PRINTJOB/ENDPRINTJOB 


The  following  program  code  prints  three  copies  of  a  report  from  page  ten  to 
the  end,  and  ejects  a  page  after  the  printing.  The  REPORT  FORM  command 
that  runs  the  report  contains  the  PRINTJOB  construct  so  you  don’t  need  to 
issue  the  PRINTJOB/ENDPRINTJOB  commands  when  using  REPORT 
FORM.  This  routine  resets  _pbpage  and  .pcopies  to  their  default  values  after 
the  printjob  executes.  You  don’t  need  to  reset  _peject,  since  you  should 
define  it  for  each  subsequent  printjob. 

_pfcpaga  *  10 
_pej«ct  *  'AFTER' 

.jxcpica  *  3 

REPORT  FORM  Accants  TO  PRINT 
-Sfcpage  =  0 
_pocpie*  =  1 


See  Also 

DATE(),  EOF(),  ON  PAGE,  PROCEDURE,  REPORT  FORM,  RETURN,  SET 
PRINTER,  SET  TALK,  _pcopies,  _pecodes,  _peject,  _plineno,  _pscodes 


i 


LANGUAGE  REFERENCE 


2-193 


JOBNAHE:  PAGE:  194  SESS:  6  Ued  Hay  11  11:38:55  1988 

©tate/di sk2/al  I j  obz/CLS_jnanhat /GRP_manha  t  /  JOB_man l angref /DI V_l  rchap2e 


PRIVATE 


PRIVATE  allows  you  to  create  local  memory  variables  and  array  elements, 
without  overwriting  PUBLIC  memory  variables  and  array  elements  with  the 
same  name. 


Syntax 


PRIVATE  ALL  [LIKE/EXCEPT  <  skeleton  >  ] 

PRIVATE  <  memvar  list >  /ARRAY  <  array  definition  list > 


Usage 

Changes  made  to  a  PRIVATE  memory  variable  do  not  overwrite  the  value  of 
a  memory  variable  with  the  same  name  created  in  another  program.  Previ- 
ous  values  of  PRIVATE  memory  variables  are  retained  in  memory  with  the 
names  of  the  programs  that  created  them. 

When  the  program  containing  PRIVATE  memory  variables  ends,  the  values 
that  were  hidden  by  PRIVATE  are  reinstated.  The  PRIVATE  values  are  no 
longer  in  effect. 

When  you  declare  a  system  memory  variable  in  a  dBASE  IV  procedure,  a 
PRIVATE  copy  is  created  and  it  is  assigned  the  current  value  for  that  system 
variable. 


See  Also 

DO,  PARAMETERS,  PUBLIC 
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PROCEDURE 


PROCEDURE  identifies  the  beginning  of  a  subroutine. 


Syntax 

PROCEDURE  <  procedure  name> 


Usage 


A  procedure  is  a  useful  subroutine  that  you  run  with  the  command  DO 
<  procedure  >  .  You  can  incorporate  procedures  directly  into  a  program 
file,  or  put  them  into  a  separate  procedure  file.  dBASE  IV  will  search  for  the 
procedure  in  the  following  order: 

1.  Look  in  the  current  object  file. 

2.  Look  in  the  SET  PROCEDURE  file. 

3.  Look  in  other  open  object  files,  in  most-recently-opened  order. 

4.  Look  for  an  object  file  with  the  procedure  name,  and  open  it. 

5.  Look  for  a  program  file  with  the  procedure  name,  and  compile  it. 

6.  Look  for  an  SQL  program  file  with  the  procedure  name,  and  compile  it. 

You  can  repeat  procedure  names,  because  the  above  search  pattern  can 
effectively  hide  one  procedure  in  favor  of  another  that  is  higher  up  in  the 
search  path. 

You  can  put  as  many  procedures  in  a  program  or  procedure  file  as  available 
RAM  permits,  up  to  a  maximum  of  1,170  procedures  per  file.  Each  proce¬ 
dure  must  begin  with  the  keyword  PROCEDURE  and  end  with  RETURN. 

Procedure  names  may  be  up  to  eight  characters  long.  They  may  contain 
letters,  numbers,  and  underscores,  and  must  begin  with  a  letter.  You  should 
not  assign  the  same  name  to  a  program  file  and  to  a  procedure  contained  in 
the  program  file. 

Programming  Notes 

dBASE  IV  maintains  a  procedure  list  at  the  beginning  of  every  object  (.dbo) 
file.  It  treats  the  main  program  itself  as  a  procedure,  giving  it  a  procedure 
name  that  matches  the  source  program  filename.  This  procedure  name  is 
the  first  one  in  the  procedure  list.  Each  subsequent  procedure,  whether  con¬ 
tained  in  the  current  source  file  or  in  a  separate  procedure  file,  is  added  to 
the  list  when  the  source  file  is  compiled  to  an  object  file. 
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PROCEDURE 


For  example,  suppose  you  have  the  following  program,  Main: 


*tein.prg 

<COTTTBrdS> 

DO  A 
DO  B 
DO  C 
RETUN 

PRXEDLRE  A 
<ocnnards> 
RETIR1 

PRXEDLFE  B 
<comards> 
RETURN 

PRXEDLRE  C 
<ocrmards> 
RETLRJ 


dBASE  IV  will  include  four  procedures  in  the  procedure  list  for  the  com¬ 
piled  object  file:  Main  (the  default  procedure  name).  A,  B,  and  C.  Note  that 
only  code  at  the  beginning  of  a  program  file  is  assigned  the  default  proce¬ 
dure  name. 

Putting  the  procedures  in  the  main  program  file  eliminates  the  need  for 
many  separate  program  files.  This  makes  programs  run  more  quickly,  since 
dBASE  IV  does  not  have  to  open  and  close  these  programs  before  running 
them.  You  can  still  use  the  SET  PROCEDURE  TO  <  procedure  file>  for 
procedures  to  be  activated  v'ith  the  DO  command. 

Any  procedure  found  in  an  active  object  file  is  available  for  the  DO 
<  procedure  name>  command.  If  A.dbo  calls  B.dbo  calls  C.dbo,  all  the  pro¬ 
cedures  defined  within  A,  B,  and  C  are  available  to  any  procedures  in  C. 
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PROCEDURE 


Examples 

The  following  file  contains  two  routines  which  are  used  to  output  specific 
messages  to  the  screen: 


*  This  is  an  example  of  the  procedre  file  Procl.prg 

PfCCEDLRE  Messagel 
3  15,0  CLEW 

a  18^0  SAY  'The  account  is  new  cverdrawf 
RETUW 

ramre  Message2 
a  10,0  CLEW 

a  15,10  SAY  'Payment  has  not  been  receivecf 
3  17,10  SAY  "Please  issue  account  hold1 
RETUN 

*  ECP:  Procl.prg 


To  activate  a  procedure  within  Procl.prg: 


.  SET  PROCEDURE  TO  Prod 
.  DO  Messagel 

See  Also 

COMPILE,  DO,  PARAMETERS,  RETRY,  RETURN,  SET  PROCEDURE 
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PROTECT 


PROTECT  creates  and  maintains  security  on  a  dBASE  IV  system. 

Syntax 

PROTECT 

Usage 

This  menu-driven  command  is  issued  within  dBASE  IV  by  the  database 
administrator,  who  is  responsible  for  data  security.  PROTECT  works  in 
single-user  or  multi-user  environment. 

PROTECT  is  optional.  If  you  use  it,*the  security  system  always  controls 
base  file  access.  '•  A 

This  command  displays  a  full-screen  menu.  The  first  time  you  use  PROTECT, 
the  system  prompts  you  to  enter  and  confirm  an  administrator  password. 


WARNING 

Remembering  the  administrator  password  is  essential.  You  can 
access  the  security  system  only  if  you  can  supply  the  password.  Once 
established,  the  security  system  can  be  changed  only  if  you  enter  the 
administrator  password  when  you  call  PROTECT.  Keep  a  hard  copy 
of  the  database  administrator  password  in  a  secured  area.  There  is 
no  way  to  retrieve  this  password  from  the  system. 


a 

data-  hocue 


You  must  add  at  least  one  user  when  you  use  PROTECT  for  the  first  time.  If 
you  fail  to  do  so,  you  will  not  be  able  to  enter  dBASE  IV. 

If  you  intend  to  use  SQL,  you  must  add  the  super  user  log-in  name  SQLDBA, 
which  is  granted  privileges  to  all  operations  in  SQL  mode.  The  SQL  GRANT 
and  REVOKE  commands  control  file  and  field  access  privileges  using  log-in 
names  assigned  by  PROTECT. 

PROTECT  includes  three  distinct  types  of  database  protection: 

■  Log-in  security ,  which  prevents  access  to  dBASE  IV  by  unauthorized 
personnel 

■  File  and  Held  access  security ,  which  allows  you  to  define  what  files,  and 
fields  within  files,  each  user  can  access 

■  Data  encryption,  which  encrypts  dBASE  files  so  that  unauthorized  users 
cannot  read  them 
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PROTECT 


Thble  2-5  summarizes  the  database  security  types,  how  to  implement  each 
security  type,  and  the  results  of  security  implementation. 


Table  2-6  dBASE  security  summary 


Security  Type 

Ybu  Define: 

You  Get: 

Log-in 

User  name  and  password 

Control  over  access  to 
dBASE IV 

File  and  Field 

Access  levels 

Control  over  access  to  data 

Access 

files,  fields  in  data  files,  and 
application  code 

Data  Encryption 

User  and  file  group 

Automatic  encryption  and 
decryption  of  data 

It  is  not  necessary  to  implement  all  three  levels  of  security;  you  can  stop  at 
the  log-in  level,  if  you  wish.  You  must  implement  the  security  types  in  the 
order  shown  in  Table  2-5. 

Log-in  security  is  the  first  security  level.  Once  a  security  system  is  in  place, 
users  cannot  access  dBASE  IV  until  they  pass  log-in  security. 

Access  control  is  the  next  security  level.  Access  control  determines  what  a 
user  can  do  both  with  a  database  file  and  the  data  in  the  Hie,  and  can  be 
used  to  control  processing  of  application  code.  User  access  levels  are  num¬ 
bered  1  through  8,  where  1  has  the  greatest  and  8  the  lowest  access  privi¬ 
leges.  You  establish  an  access  level  for  each  user  in  the  user’s  profile,  and 
additional  access  levels  for  file  and  field  privileges  in  the  file  privilege 
scheme. 

You  establish  privileges  for  a  database  file  by  assigning  access  levels,  in  any 
combination,  for  read,  update,  extend,  and  delete  operations. 

Data  encryption  scrambles  the  database  so  that  unauthorized  users  cannot 
read  the  information  in  the  file. 

The  Dbsystem.db  Fie 

PROTECT  builds  and  maintains  a  password  system  file,  called  Dbsystem.db, 
which  contains  a  record  for  each  user  who  accesses  a  PROTECTed  system. 
Each  record,  called  a  user  profile,  contains  the  user’s  log-in  name,  account 
name,  password,  group  name,  and  access  level.  When  a  user  enters  the 
dBASE  command  at  a  network  workstation,  dBASE  IV  looks  for  a 
Dbsystem.db  file.  If  it  finds  this  file,  it  initiates  the  log-in  process.  If  it  does 
not  find  this  file,  there  is  no  log-in  process. 
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PROTECT 


Dbsystem.db  is  maintained  as  an  encrypted  file.  You  will  probably  want  to 
keep  a  hard  copy  record  of  some  or  all  of  the  information  contained  in 
Dbsystem  .db.  For  example,  if  a  user  forgets  a  log-in  value  (such  as  group, 
log-in  name,  or  password),  you  will  want  to  have  that  information  available. 

The  Reports  menu  allows  you  to  display  or  print  security  information  about 
users  and  files. 

File  Privileges 

You  can  create  file  privilege  schemes  for  up  to  eight  database  files  at  a  time. 

If  you  try  to  set  up  a  ninth  file,  you  will  get  the  error  message  Too  many 
files  are  open.  When  you  have  finished  creating  the  eighth  scheme,  you 
must  store  and  save  these  eight  privilege  schemes  before  creating  any  more. 

File  access  rights  cannot  override  a  read-only  attribute  established  for  the 
file  at  the  operating  system  level. 

Changing  a  File  Privilege  Scheme 

When  you  select  a  file,  PROTECT  checks  to  see  if  the  file  privilege  scheme 
has  already  been  defined.  If  it  has,  the  rest  of  the  menu  items  are  completed 
with  their  current  values.  You  can  then  change  any  of  the  values.  If  the  file 
privilege  scheme  has  already  been  saved,  the  message  <  filename >  .crp 
already  exists,  overwrite  it?  (Y/N)  appears.  Press  Y  if  you  wish  to  change 
any  values.  (This  is  not  affected  by  the  status  of  SET  SAFETY.) 

After  you  make  your  changes,  store  and  save  them. 

Exiting  from  PROTECT 

The  Exit  menu  contains  three  options: 

Select  Save  to  post  all  new  and  updated  user  profiles  and  file  privilege 
schemes  that  have  been  stored  during  the  current  PROTECT  session.  User 
profiles  are  saved  in  the  current  Dbsystem.db  file.  File  privilege  schemes  are 
saved  in  the  database  file  structure.  You  can  save  user  profiles  at  any  point 
during  a  PROTECT  session.  You  must  save  file  privilege  schemes  after  you 
define  or  change  eight  of  them.  Database  files  are  encrypted  when  a  file  priv¬ 
ilege  scheme  is  saved. 

Select  Abandon  to  cancel  all  new  and  updated  user  profiles  and  file  privi¬ 
lege  schemes  not  already  saved  during  the  current  PROTECT  session. 

Select  Exit  to  terminate  the  current  PROTECT  session.  New  and  updated 
user  profiles  and  updated  file  privilege  schemes  will  be  encrypted  and  saved, 
if  they  have  not  already  gone  through  this  process. 
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Data  Encryption 

If  your  database  system  is  PROTECTed,  dBASE  IV  automatically  encrypts  and 
decrypts  database  files  and  their  associated  index  and  memo  files. 

When  a  database  file’s  privilege  scheme  is  saved,  PROTECT  creates  an 
encrypted  version  of  the  database  file  with  a  .crp  extension.  You  may  want 
to  copy  the  unencrypted  file,  for  reference,  to  a  floppy  disk  and  store  the 
floppy  disk  in  a  secure  place.  To  use  MODIFY  STRUCTURE,  you  need 
unencrypted  versions  of  a  database  file. 

To  enable  security,  you  should: 

1.  Copy  the  encrypted  file  (.crp)  over  the  unencrypted  file  (.dbf)  and 
change  the  extension  to  .dbf,  as  follows: 

.  RLN  CCPf  Filename,  crp  Filename.cbf 

2.  Delete  the  .crp  file,  as  follows: 

.  ERASE  Filename,  crp 

3.  Rename  the  .cpt  file  so  that  it  has  a  .dpt  extension. 

Index  files  are  only  encrypted  when  you  REINDEX  or  create  them  with  an 
encrypted  database  file. 

You  can  control  when  copied  files  are  encrypted  through  the  SET 
ENCRYPTION  command. 

See  Also 

SET  ENCRYPTION 

If  you  purchased  dBASE  IV,  see  Chapter  14,  “dBASE  Security,”  in  Advanced 
Topics  for  more  information  about  PROTECT. 

If  you  purchased  dBASE  IV  Developer’s  Edition,  see  Chapter  5,  “dBASE 
Security,”  in  Networking  with  dBASE  IV. 
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PUBLIC 


PUBLIC  designates  specified  memory  variables  and  array  elements  that  you 
can  use  and  alter  in  any  dBASE  program  or  subprogram.  Unlike  private 
memory  variables  and  array  elements,  they  are  not  released  when  the 
program  ends. 

Syntax 

PUBLIC  <  memory  variable  list >  /[ARRAY  <  array  definition  list>  ] 


Usage 

PUBLIC  memory  variables  or  array  elements  are  global  variables  that  you 
can  call  from  any  program.  Memory  variables  that  you  want  to  be  global 
must  be  declared  PUBLIC  before  they  are  given  values.  Specifying  a  memory 
variable  or  system^variable  from  the  dot  prompt  declares  it  to  be  PUBLIC. 
The  values  of  system  variables  may  be  changed  by  any  program  that  uses 
them,  but  the  original  values  are  returned  when  you  quit  the  program. 

The  value  of  a  PUBLIC  memory  variable  may  be  hidden  temporarily  when  a 
program  or  procedure  file  is  called,  by  declaring  memory  variables  with  the 
same  name  PRIVATE,  or  by  passing  a  parameter  with  the  DO  <  procedure > 
WITH  <  parameter  list >  command. 

Variables  saved  in  a  memory  file  are  always  RESTOREd  as  PUBLIC  variables, 
if  they  are  restored  at  the  dot  prompt.  Variables  restored  from  a  memory  file 
in  a  dBASE  program  are  RESTOREd  as  PRIVATE  variables  unless  you  specify 
otherwise.  To  RESTORE  PUBLIC  variables  in  a  dBASE  program  file,  you  first 
need  to  redeclare  the  variables  you  intend  to  be  PUBLIC  as  PUBLIC  varia¬ 
bles.  RESTORE  FROM  <  file  name  >  ADDITIVE  then  restores  the  variables 
as  PUBLIC,  overwriting  any  variables  of  the  same  name. 


NOTE 

Variables  you  declare  PUBLIC  are  stored  as  logical  type  variables  until 
you  initialize  them. 


MtW[ 
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Example 

Within  a  dBASE  program  file,  the  Page  and  Answer  memory  variables  are 
declared  PUBLIC  and  initialized  when  the  following  commands  are 
executed: 


*ftain.prg 
DO  Ini  Oar 
RETLH'J 

FTOCEDLRE  Ini  Oar 
PLBLIC  Page,  Atswer 
Rage  =  1 
Answer  =  "Y* 

RETIRJ 


See  Also 

DECLARE,  DO,  PARAMETERS,  PRIVATE,  RELEASE,  RESTORE,  SAVE, 
STORE 
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QUIT 


QUIT  closes  all  open  files,  terminates  the  dBASE  IV  session,  and  returns 
control  to  the  operating  system. 

Syntax 

QUIT 

Usage 

This  is  the  only  safe  method  for  exiting  from  dBASE  IV  and  returning  to 
your  computer's  operating  system.  Exiting  dBASE  IV  by  resetting  your  com¬ 
puter  may  damage  open  files  and  cause  data  loss. 
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READ 


READ  activates  all  @...GETs  issued  since  the  last  CLEAR,  CLEAR  ALL, 
CLEAR  GETS,  or  READ  command.  It  is  most  commonly  used  in  dBASE 
program  files  for  full-screen  entry  or  editing  data. 


Syntax 

READ  [SAVE] 

Usage 

This  command  allows  you  to  receive  user  input  into  memory  variables  and 
fields.  Use  it  with  @...GET  to  place  the  input  into  memory  variables.  When 
you  want  to  receive  several  pieces  of  information  instead  of  a  one-time  user 
input  (such  as  with  ACCEPT,  INPUT,  or  WAIT),  use  several  @...GET  state¬ 
ments  followed  by  a  single  READ. 

The  READ  command  uses  the  same  full-screen  editing  keys  as  the  APPEND 
and  EDIT  commands. You  must  use  READ  to  edit  memory  variables  with  the 
@  command.  /' 

READ  clears  all  GETs  after  you  finish  editing,  unless  you  use  the  SAVE 
option. 


Option 

READ  SAVE  does  not  clear  GETs.  This  means  that  the  next  time  you  issue 
READ,  the  same  set  of  GETs  appears  for  editing.  If  using  the  READ  SAVE 
option,  make  sure  you  issue  CLEAR  GETS  before  the  next  READ. 


Programming  Note 

If  you  want  to  use  a  multi-page  format  (.fmt)  file  in  which  the 
@ .. .SAY. .''.GETs  continue  on  from  2  to  32  screen  pages,  include  a  READ 
wherever  you  want  a  page  break. 
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READ 


Example 

Use  the  READ  command  to  edit  the  contents  of  a  memory  variable: 


.  SWRE  SPACE  (25)  TO  fame 
.  a  10,10  SAY  ’Biter  >clt  name:  ’  GET  fame 
.  READ 

READ  puts  the  cursor  into  the  Mname  variable  to  allow  editing.  The 
SPACE(25)  function  initializes  a  blank  character  string  that  is  25  characters 
long. 


See  Also 

@,  CLEAR,  CLEAR  GETS,  CLEAR  MEMORY,  CREATE/ MODIFY  SCREEN, 
REPLACE,  SET  DEVICE,  SET  FORMAT,  STORE 
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RECALL 


RECALL  reinstates  records  that  are  marked  for  deletion  in  the  active  data¬ 
base  file. 


Syntax 

RECALL  [  <  scope  >  ]  [FOR  <  condition  >  ]  [WHILE  <  condition  >  ] 


Default 


Unless  otherwise  specified  by  the  <  scope  >  or  the  FOR  or  WHILE  clauses, 
only  the  current  record  is  RECALLed. 


Special  Cases 

RECALL  does  not  reinstate  records  that  have  been  removed  from  the  data¬ 
base  by  the  PACK  or  ZAP  commands. 

RECALL  has  no  effect  with  SET  DELETED  ON.  If  SET  DELETED  is  ON,  you 
must  specify  which  records  to  RECALL  with  RECALL  RECORD  <  n>  . 


Examples 

To  reinstate  only  the  first  record  in  the  database,  assuming  that  records  1,  5, 
and  10  are  marked  for  deletion  with  DELETE: 


.  USE  Stack 
.  RECALL 

1  record  recalled 


To  reinstate  record  10: 


.  RECALL  RECORD  10 

1  record  recalled 

To  reinstate  record  5  and  any  other  records  that  have  been  marked  for 
deletion: 


.  RECALL  ALL 

17  records  recalled 


See  Also 

DELETE,  DELETEDQ,  PACK,  SET  DELETED,  ZAP 
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REINDEX 


REINDEX  rebuilds  all  active  index  (.ndx)  and  multiple  index  (.mdx)  files  in 
the  current  work  area. 


Syntax 

REINDEX 


Usage 

This  command  reindexes  all  open  ndx  and  .mdx  files  in  the  current  work 
area.  Whenever  you  REINDEX  files  that  were  created  with  SET  UNIQUE  ON 
or  with  UNIQUE  included  in  the  INDEX  syntax,  the  rebuilt  index  file  retains 
its  UNIQUE  status  regardless  of  whether  UNIQUE  is  ON  or  OFF. 

In  a  network  environment,  the  database  file  must  be  in  exclusive  use  before 
you  REINDEX. 


Example 

.  LBE  Transact 
.  REIMEX 

Rebuilding  index  -  OTOERJD 

100  X  indexed  17  Records  indexed 

Rebuilding  index  -  PART_NW€ 

100  X  indexed  17  Records  indexed 


See  Also 

INDEX,  KEY(),  MDX(),  NDX(),  PACK,  SET  INDEX,  SET  ORDER, 
SET  UNIQUE,  USE,  ZAP 
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RELEASE  deletes  memory  variables,  thus  opening  memory  space  for  other 
use.  RELEASE  is  also  used  with  the  appropriate  keyword  to  remove  LOADed 
assembly  language  programs,  menus,  popups,  and  windows  from  memory. 


Syntax 


RELEASE  <  memvar  list  > 


RELEASE  ALL  [LIKE/ EXCEPT  <  skeleton  >  ] 


RELEASE  MODULE  <  module  name  list  >  /MENUS  <  menu  name  list > 
/POPUPS  <  popup  name  list >  /WINDOW  <  window  name  list > 


Usage 

In  the  interactive  mode,  RELEASE  ALL  deletes  all  memory  variables  except 
system  variables.  Within  a  program,  RELEASE  ALL  deletes  only  PRIVATE 
memory  variables  created  in  the  current  program  or  in  lower  level  pro¬ 
grams.  It  does  not  delete  PRIVATE  variables  created  in  higher-level  pro¬ 
grams,  except  when  used  from  the  dot  prompt. 


Options 

<  memvar  list >  is  a  list  of  names  separated  by  commas. 

RELEASE  MODULE  removes  a  LOADed  module  from  memory.  This  allows 
you  to  remove  LOADed  assembly  language  program  modules  from  memory. 

RELEASE  MENUS  erases  bar  menus  from  the  screen  and  releases  them  from 
memory.  It  removes  the  menus  in  the  menu  name  list  from  memory,  deacti¬ 
vating  any  active  menu.  If  no  name  list  is  used,  then  it  clears  all  menus  from 
memory.  It  is  recommended  that  you  DEACTIVATE  menus  before  you  release 
them,  to  make  sure  that  any  ON  SELECTION  and  ON  PAD  commands  associ¬ 
ated  with  the  menus  are  cleared. 

Ifyou^define  menus  in  procedures,  you  can  release  menus  from  memory 
any  time  and  recover  them  by  DOing  the  procedure  that  defines  them. 

RELEASE  POPUPS  erases  the  named  pop-up  menus  from  the  screen  and 
from  memory.  It  deactivates  the  active  pop-up  menu,  if  you  specify  it  in  the 
pop-up  name  list.  Any  ON  SELECTION  POPUP  commands  associated  with 
the  pop-up  menus  in  the  name  list  are  cleared  before  the  pop-up  menus  are 
erased.  If  you  use  no  pop-up  menu  name  list,  this  command  erases  all  pop¬ 
up  menus  from  the  screen  and  from  memory. 
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RELEASE 


RELEASE  WINDOW  erases  specified  windows  from  the  screen  and  releases 
them  from  memory.  The  window  name  list  contains  the  names  of  previously 
defined  windows,  separated  by  commas.  Any  text  covered  by  the  released 
windows  is  restored  to  the  screen.  You  can  selectively  remove  windows  from 
memory  with  this  command. 


Examples 

To  RELEASE  all  memory  variables  starting  with  the  letter  m : 

.  RESTORE  FROM  fern 
.  RELEASE  ALL  LIKE  nr* 


To  RELEASE  all  memory  variables  except  those  that  have  the  letter _x.as  the 
third  character: 


(2 


.  RESTORE  FROM  Man 
.  RELEASE  ALL  EXC&T  ??x* 


To  RELEASE  the  Mvar,  Pages,  Pgxl,  and  Pgx2  variables: 


.  RESTORE  FROM  fem 
.  RELEASE  tier,  Pages,  F&ri,  F&2 


See  Also 

CALL,  CALL(),  CLEAR  ALL.  CLEAR  MEMORY,  LOAD,  RESTORE,  RETURN, 
SAVE,  STORE 
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RENAME 


RENAME  changes  the  name  of  a  file. 


Syntax 

RENAME  <  old  filename  >  TO  <  new  filename  > 


Defaults 

Both  the  old  and  new  filenames  must  include  file  extensions.  If  the  files  are 
not  on  the  default  drive,  precede  the  filenames  with  the  path  or  drive 
designation. 


Usage 

Use  this  command  to  change  the  names  of  disk  files  without  exiting  to  the 
operating  system.  You  can  not  RENAME  an  open  file,  and  the  new  filename 
cannot  be  an  existing  filename  in  the  same  directory. 

If  you  rename  a  database  file  with  an  associated  memo  file,  you  must  also 
rename  the  corresponding  memo  (.dbt)  file  to  match. 

Special  Case 

Do  not  use  the  letters  A  through  J,  or  M,  as  database  filenames  because  they 
are  reserved  for  alias  names.  However,  you  can  specify  AAas  a  valid  data¬ 
base  filename. 


Examples 

To  RENAME  a  database  file  named  School. dbf  to  Roster. dbf: 

.  A9IMF  School. cbf  TO  toster.cbf 

To  RENAME  the  file  Letters.jim  to  Memos. old,  assuming  that  B  is  not  the 
default  drive: 

c  RBWG  B:Letters.jim  TO  B:Maros.old 


See  Also 

CLOSE,  COPY,  COPY  FILE,  USE 
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REPLACE 


REPLACE  changes  the  contents  of  specified  fields  in  the  active  database  file. 

Syntax 

REPLACE  <  field  namel>  WITH  <  expl>  [,<  field  name2>  WITH 

<  exp2>  ...]  [<  scope  >  ]  [FOR  <  condition  >  ]  [WHILE 

<  condition  >  ]  [ADDITIVE] 

Default 

Unless  otherwise  specified  by  the  scope  or  the  FOR  or  WHILE  clause,  only 
the  current  record  is  replaced. 


Usage 


REPLACE  overwrites  a  specified  field  with  new  data.  The  field  you  select 
can  be  any  type,  including  a  memo  Held;  however,  the  field  and  the  WITH 
expression  must  have  the  same  data  type.  In  numeric  fields,  the  WITH 
expression  may  be  larger  than  the  field  width,  in  which  case  the  number  is 
displayed  in  scientific  notation.  In  converting  memo  fields  to  character 
fields,  REPLACE  truncates  the  data  to  fit  into  the  assigned  field  width. 

The  ADDITIVE  clause  lets  you  build  a  memo  field  from  several  character 
strings.  This  clause  is  ignored  unless  the  field  is  a  memo  field. 


NOTE 


Replacements  on  a  key  field  of  an  indexed  database  file  also  update 
the  index  file  if  it's  in  use.  When  the  replacement  is  made,  the  record 
moves  to  a  new  position  in  the  index  file.  If  you  specify  a  scope,  FOR, 
or  WHILE  when  making  replacements  on  an  indexed  field,  all  of  the 
records  you  intended  may  not  be  replaced.  For  example,  if  you 
REPLACE  ALL,  only  the  first  record  and  those  that  follow  the  new  key 
field  value  will  be  replaced.  That’s  because  each  record  is  reindexed 
as  the  REPLACE  is  done,  and  the  record  pointer  is  moved  to  follow 
the  replaced  record.  To  REPLACE  all  the  records,  you  should  use  the 
database  file  without  an  index. 


Record  Pointer 

The  REPLACE  command  does  not  reposition  the  record  pointer  unless  you 
specify  a  scope,  FOR,  or  WHILE.  If  the  record  pointer  is  at  the  end  of  the  file 
(EOF()  is  .T.),  no  replacements  are  made  unless  you  specify  a  scope  or  FOR 
condition  in  the  command. 
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REPLACE 


Examples 

These  examples  use  the  Stock. dbf  database  file.  The  first  example  changes 
the  cost  for  those  records  that  match  the  specified  condition: 

.  LSEStock 

.  RERJCE  Itenuxjst  WITH  1303.00  FCR  Part-id  =  C-222-1000 
2  Records  Replaced 


To  raise  the  cost  of  all  items  by  ten  percent: 

.  RERJCE  ALL  Itenuxst  WITH  ItenLpost  *  1. 1 
17  Reoxds  Rg^laced 


See  Also 

ORDER,  REINDEX,  SET  INDEX,  SET  ORDER,  STORE 
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REPORT  FORM 


REPORT  FORM  prints  information  from  the  active  database  using  a  report 
form  file  created  by  CREATE/MODIFY  REPORT.  You  may  direct  a  report  to 
the  screen,  the  printer,  or  to  an  ASCII  text  file. 


Syntax 

REPORT  FORM  <  report  form  filename  >  /?  [PLAIN]  [HEADING  <  expC>  ] 
[NOEJECT]  [SUMMARY]  [<  scope  >  ]  [FOR  <  condition  >  ] 

[ WHILE <  condition  >  ]  [TO  PRINTER/TO  FILE  <  filename  >  ] 


Defaults 

The  default  extension  is  .frm  for  the  FORM  filename. 

Unless  otherwise  specified  by  the  scope,  a  FOR  condition,  or  an  active  filter 
condition  or  query  file,  all  records  in  the  database  are  included  in  the  report. 


Usage 

First,  CREATE  report  form  files  by  issuing  CREATE/MODIFY  REPORT. 

If  group  subtotals  are  defined  in  the  report  form  file,  the  active  database 
or  view  must  be  INDEXed  or  SORTed  on  the  same  fields  as  the  group 
expression. 

In  multi-user  operations,  the  REPORT  FORM  command  places  an  automatic 
lock  on  the  database  file  before  printing.  If  another  user  has  used  RLOCK() 
or  FLOCKQ  on  the  file,  REPORT  FORM  generates  the  File  is  in  use  by 
another  error  message.  You  may  copy  the  file  to  a  temporary  file  to  generate 
the  report. 


Options 

Use  the  catalog  query  clause,  ?,  to  activate  a  menu  of  all  report  forms  for  the 
active  database  file. 

PLAIN  causes  the  report  to  print  without  page  numbers  or  a  system  date. 

The  page  heading  defined  in  the  report  form  file  appears  on  the  first  page 
only. 

HEADING,  followed  by  a  character  expression,  defines  an  extra  heading  that 
is  printed  on  the  first  line  of  each  page.  If  the  heading  is  a  character  string, 
you  must  delimit  it.  PLAIN  and  HEADING  are  mutually  exclusive,  with 
PLAIN  taking  precedence. 

NOEJECT,  with  TO  PRINTER,  suppresses  the  usual  initial  form  feed,  causing 
the  report  to  print  on  the  first  page  that  comes  up  in  the  printer. 
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REPORT  FORM 


The  semicolon  (;)  character  in  a  character  or  memo  field  causes  a  carriage 
return  and  line  feed  in  a  report  form.  This  semicolon  does  not  print. 

TO  FILE  sends  the  report  to  a  text  (.txt)  file  on  the  default  drive  and  displays 
it  on  the  screen,  unless  otherwise  directed. 

SUMMARY  suppresses  display  of  detail  lines,  showing  only  subtotals  and 
totals  on  the  report. 


Tip 


To  print  a  memo  field  from  another  work  area  using  REPORT  FORM, 
include  a  SET  FIELDS  command  before  creating  the  format  file  and  do  not 
include  the  memo  field  alias  name  in  the  Columns:Field  contents. 


See  Also 


CREATE/MODIFY  REPORT,  REPORT  FORM 
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RESET 


The  RESET  command  removes  the  integrity  tag  from  a  file. 

Syntax 

RESET  [IN  <  alias  name>  ] 

Usage 

The  integrity  tag  marks  files  involved  in  a  transaction  begun  by  a  BEGIN 
TRANSACTION  command.  This  tag  stays  on  a  file  until  the  transaction  is 
completed,  or  a  successful  ROLLBACK  has  occurred. 

You  may  need  to  remove  this  tag  with  the  RESET  IN  <  alias  name> 
command,  if  you  do  not  want  to  ROLLBACK  a  database  file,  or  if  a  success¬ 
ful  ROLLBACK  is  not  possible. 

<  alias  name>  is  the  alias  name  of  a  database  file  open  in  another  work 
area. 

After  issuing  a  RESET  command,  you  can  access  the  file  for  another 
transaction. 


Example 

If  you  purchased  dBASE  IV  Developer’s  Edition,  please  see  Networking  with 
d BASE  IV 

See  Also 

BEGIN  TRANSACTION,  END  TRANSACTION,  ISMARKEDQ,  ROLLBACK, 
ROLLBACKQ 
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RESTORE  retrieves  and  activates  memory  variables  and  arrays  from  a 
memory  file. 


Syntax 

RESTORE  FROM  <  filenames  [ADDITIVE] 

Defaults 

A. mem  file  extension  is  assumed,  unless  you  specify  otherwise. 


When  you  RESTORE  memory  variables,  all  of  the  currently  active  variables 
are  deleted  unless  you  have  included  the  ADDITIVE  option.  These  variables 
are  restored  as  PRIVATE  in  a  dBASE  program  file,  unless  you  first  declare 
them  as  PUBLIC  and  specify  ADDITIVE.  Memory  variables  you  restore  from 
the  dot  prompt,  however,  always  come  back  as  PUBLIC. 

You  can  have  up  to  25,000  memory  variables  available  to  you  if  you  specify 
this  amount  in  the  Config.db  file.  The  default  number  is  500.  It  is  possible, 
however,  that  your  available  memory  will  limit  the  maximum  number  of 
memory  variables  you  can  use.  See  Chapter  6,  "Customizing  dBASE  IV,”  for 
more  information  on  memory  variable  default  sizes  and  how  you  can  change 
them  in  Config.db. 


Options 

To  retain  the  current  memory  variables,  include  the  ADDITIVE  option, 
which  causes  the  RESTOREd  memory  variables  to  be  added  to  the  current 
ones.  Any  current  memory  variables  with  the  same  name  are  overwritten.  To 
restore  variables  in  a  memory  file  as  PUBLIC,  you  must  redeclare  them  as 
PUBLIC  before  you  RESTORE  the  memory  file,  and  you  must  use  the 
ADDITIVE  option. 


See  Also 

PUBLIC,  RELEASE,  SAVE,  STORE 
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RESTORE  MACROS 


RESTORE  MACROS  restores  macros  that  were  saved  to  a  file. 

Syntax 

RESTORE  MACROS  FROM  <  macro  file  > 

Usage 

A  macro  (.mcr)  file  is  created  when  you  issue  the  SAVE  MACROS  command, 
and  contains  all  the  macros  that  were  in  memory.  RESTORE  MACROS 
restores  macros  from  an  existing  file  for  use  during  the  current  dBASE  IV 
session. 

If  you  save  your  macros  to  a  file  with  an  extension  other  than  .mcr,  remem¬ 
ber  to  specify  that  extension  when  restoring  the  macro  file  later. 


When  you  restore  macros  from  a  file  into  memory,  current  macros  assigned 
to  the  same  keys  as  the  restored  macros  will  be  overwritten. 


NOTE 

The  .mac  extension  is  used  by  the  dBASE  IV  Applications  Generator. 
Do  not  use  the  .mac  extension  for  your  macro  files. 


Example 

All  macros  are  restored  to  memory  with  the  command: 

.  RESIDE  HVRDS  FRDN  Hscdeno 

This  command  restores  all  macros  saved  in  the  Macdemo.mcr  file  to 
memory. 

See  Also 

PLAY  MACRO,  SAVE  MACROS 
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RESTORE  WINDOW 


The  RESTORE  WINDOW  command  restores  window  definitions  from  a  disk 
file  to  memory. 


Syntax 

RESTORE  WINDOW  <  window  name  list >  /ALL  FROM  <  filename  > 

Usage 

Use  this  command  to  restore  window  definitions  from  a  disk  file  created 
with  the  SAVE  WINDOW  command.  The  default  extension  for  window  defini¬ 
tion  files  is  .win. 

You  can  restore  windows  selectively;  not  all  the  window  names  have  to  be 
restored  from  a  given  .win  file.  You  can  also  restore  windows  in  any  order, 
regardless  of  the  order  you  used  with  the  SAVE  WINDOW  command.  If  you 
specify  ALL,  then  all  window  definitions  saved  in  the  .win  file  are  restored. 

If  you  used  an  extension  other  than  .win  when  saving  the  window  defini¬ 
tions,  you  must  specify  it  with  the  filename  you  give  the  RESTORE  WINDOW 
command. 

If  you  restore  a  window  name  that  is  also  currently  defined  in  memory,  the 
restored  window  definition  overwrites  the  definition  in  memory. 

See  Also 

DEFINE  WINDOW,  SAVE  WINDOW 
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RESUME 


RESUME  works  in  conjunction  with  SUSPEND.  It  causes  a  SUSPENDed  pro¬ 
gram  to  continue  executing. 

Syntax 

RESUME 

Usage 

When  you  issue  the  RESUME  command,  the  previously  SUSPENDed  com¬ 
mand  file  restarts  execution  at  the  command  line  immediately  following  the 
line  on  which  you  stopped  the  file.  If  you  entered  the  ROLLBACK  command 
during  a  SUSPENDed  transaction,  the  RESUME  command  will  be  the  same 
as  executing  a  CANCEL. 

RESUME  also  works  with  the  DEBUG  command. 


Tip 

Issuing  the  CLEAR  command  before  you  issue  RESUME  is  good  practice. 
This  ensures  that  the  commands  you  entered  while  the  program  was 
SUSPENDed  do  not  interfere  with  subsequent  screen  output. 

See  Also 

BEGIN  TRANSACTION,  C/NCEL,  CLEAR,  DEBUG,  RETURN,  ROLLBACK, 
SUSPEND 
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The  RETRY  command  re-executes  a  command,  and  may  be  used  after  an 
error  to  retry  the  command  that  caused  the  error. 


Syntax 

RETRY 


Usage 

Use  RETRY  primarily  in  error  recovery,  since  it  can  repeat  a  command  until 
it  is  successfully  executed.  Note,  however,  that  RETRY  will  not  re-evaluate 
an  IF  or  DO  WHILE  condition. 

RETRY  returns  control  to  the  calling  program  and  retries  the  command  that 
called  the  program  that  caused  the  error.  You  use  it  with  ON  ERROR  DO 
<  program  >  to  determine  where  the  error  is  in  your  program.  When 
RETRY  is  used  in  a  program  file,  it  closes  the  file.  RETRY  also  clears  out  the 
value  returned  by  the  EKRORQ  function. 

RETRY  can  be  used  in  procedures  as  well  as  in  dBASE  IV  program  files. 


Examples 

The  following  two  command  files  illustrate  a  possible  way  to  recover  from 
the  File  is  already  open  message  (error  number  3): 

*  fein.prg 

CN  ERHCR  DO  RECCVER  WITH  ERRORO 
USE  tyjile 

*  EOF:tein.prg 

*  Recover.prg 
PAfWETERS  Error 
IF  Error=3 

CLOSE  DATABASES 
BDIF 
RETRY 

*  EOF: Reader .prg 


See  Also 

ERROR(),  ON  ERROR,  RETURN 
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RETURN 


Use  RETURN  in  programs,  to  restore  control  to  calling  programs  or  to  the 
dot  prompt.  When  control  is  restored,  the  command  following  the  calling 
command  is  executed. 


Syntax 

RETURN  [TO  MASTER]  [  <  expression  >  ] 

Usage 

You  can  use  RETURN  in  both  command  and  procedure  files  and  from  the 
dot  prompt.  If  you  use  it  in  a  comm  and  file,  RETURN  closes  the  file  and 
returns  control  to  the  calling  file  or  to  the  dot  prompt.  If  you  use  the  TO 
MASTER  option  in  a  program,  control  returns  to  the  highest-level  calling 
program.  Use  it  in  a  procedure  file  to  return  control  to  the  calling  program 
or  dot  prompt,  if  the  procedure  is  the  highest  level  program.  From  the  dot 
prompt,  use  it  to  close  a  program  held  open  by  SUSPEND. 

If  you  do  not  include  the  RETURN  com  m  and  in  a  program ,  dBASE  IV  exits 
and  closes  the  program  after  it  executes  the  last  command  in  the  file.  It 
returns  to  the  program  that  called  it  or,  if  it  is  executed  in  the  highest-level 
program,  to  the  dot  prompt  or  Control  Center. 

RETURN  releases  all  PRIVATE  memory  variables  called  by  that  program, 
but  does  not  affect  PUBLIC  variables.  RETURN  also  clears  out  any  value 
returned  by  the  ERRORQ  function.  Previous  PRIVATE  values  of  system  vari¬ 
ables  are  restored. 

Use  the  <  expression  >  statement  in  user-defined  functions  to  return  the 
function  value.  RETURN  is  placed  at  the  end  of  the  user-defined  function  to 
return  the  result  of  the  function.  If  the  procedure  determines  there  is  no 
result,  it  returns  a  false  (.F.). 


See  Also 

COMPILE,  DO,  ERRORQ,  PARAMETER,  PRIVATE,  PROCEDURE,  PUBLIC, 
RESUME,  SUSPEND 
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ROLLBACK 


The  ROLLBACK  command  restores  the  database  and  index  files  to  the  state 
they  were  in  before  the  current  transaction.  It  closes  and  deletes  all  index 
and  database  files  that  may  have  been  created  during  the  transaction. 

Syntax 

ROLLBACK  [<  database  filename  >  ] 

Usage 

Use  this  command  to  undo  changes  made  to  records  in  the  database  file  after 
you  have  issued  a  BEGIN  TRANSACTION  command. 

While  a  transaction  is  active,  you  can  use  ROLLBACK  only  on  the  database 
file  that  is  currently  active  in  the  transaction.  You  cannot  use  a  database  file¬ 
name  argument  while  a  transaction  is  active. 

ROLLBACK  compares  the  transaction  log  file  with  the  active  database  con¬ 
tents,  to  undo  the  active  transaction  and  restore  the  database  file  to  what  it 
was  at  the  beginning  of  the  transaction. 

Once  a  transaction  is  terminated,  you  can  use  the  ROLLBACK  command 
only  with  a  database  filename  argument.  In  this  case,  all  ROLLBACK  does  is 
to  clear  the  file  from  being  flagged  as  in  use.  You  will  have  to  restore  the  file 
to  an  unchanged  state  manually  from  backup  copies  or  hard  copy  records. 

A  transaction  log  file  contains  the  pre-  and  post-transaction  contents  of  each 
record  that  is  altered.  The  ROLLBACK  command  refers  to  the  transaction 
log  file  to  undo  transactions.  ROLLBACK  can  fail  under  two  circumstances: 

■  If  there  are  inconsistencies  between  a  record’s  pre-  and  post-  transaction 
contents 

■  If  the  transaction  log  file  is  not  readable 

When  ROLLBACK  fails,  database  files  are  left  in  an  inconsistent  state;  there¬ 
fore,  you  should  back  up  all  files  that  are  going  to  be  involved  in  a  transac¬ 
tion  before  you  start  the  transaction.  If  ROLLBACK  should  fail,  you  can  undo 
the  transaction  by  copying  the  backup  file. 

At  the  end  of  a  successful  ROLLBACK  procedure,  the  database  file  is 
restored  to  its  pre-transaction  status.  The  transaction  log  file  is  reset  to 
the  beginning,  and  remains  open  waiting  for  a  new  transaction. 
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ROLLBACK 


Example 

This  program  segment  sets  up  for  an  automatic  ROLLBACK  with  the  ON 
ERROR  command,  before  starting  a  transaction  that  modifies  salary  records: 

CN  ERROR  ROLLBACK 
883 IN  TRANSACTION 

RS=LA£E  ALL  Salary  WITH  Salary  *  1.1 
EM)  TRANSACTION 


See  Also 

BEGIN  TRANSACTION/  END  TRANSACTION,  COMPLETED*),  ISMARKEDQ, 
RESET,  ROLLBACK() 
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RUN/! 


RUN  executes  a  specified  DOS  command,  or  any  program  which  can  be 
executed  by  DOS,  from  within  dBASE  IV. 

Syntax 

RUN  <  DOS  comm  and  > 


Usage 

RUN,  and  its  alternate  syntax  !,  executes  the  specified  DOS  command  or 
program.  When  execution  is  finished,  control  returns  to  dBASE  IV. 

RUN  requires  enough  additional  memory  for  the  DOS  Command.com  file, 
plus  the  amount  required  for  the  command  or  program  Hie  itself.  If  your 
computer  does  not  have  sufficient  memory  for  the  RUN  command,  the  mes¬ 
sage  Insnfffcieat  memory  appears. 

The  DOS  file,  Command.com,  must  be  in  the  current  directory  or  the  path 
specified  by  the  DOS  COMSPEC  parameter. 

Use  the  DOS  SET  COMSPEC  command  to  tell  the  operating  system  where  to 
find  Command.com  (for  example,  SET  COMSPEC  -  C:\command.com). 
Refer  to  your  DOS  manual  for  more  information  on  SET  and  COMSPEC. 


M  WARNING 

Some  DOS  commands,  such  as  ASSIGN  and  PRINT,  remain  in  mem¬ 
ory  after  being  RUN.  You  should  run  these  commands  before  loading 
dBASE  IV.  If  you  get  an  error  message,  clear  any  memory-resident 
programs  or  restart  your  computer  and  try  again. 


Example 

To  reset  the  system  date  from  a  memory  variable: 


.  Today  =  0 (2/29/&F 
(E/29/88 

.  RLN  DATE  STcday 
.  ?  DATEO 
(2/29/88 
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SAVE 


SAVE  stores  all  or  part  of  the  current  set  of  memory  variables  and  array 
elements  to  a  disk  file. 


Syntax 

SAVE  TO  <  filename  >  [ALL  LIKE/ EXCEPT  <  skeleton  >  ] 

Defaults 

The  filename  must  include  the  drive  designator  if  the  file  is  not  on  the 
default  drive.  Unless  otherwise  specified,  the  file  extension  for  any  file 
created  with  this  com  mand  is  mem .  If  you  do  not  use  the  ALL  LIKE/ 
EXCEPT  option,  all  current  memory  variables  are  saved  to  the  disk  file. 


Usage 


Use  SAVE  TO  to  save  memory  variables  that  you  may  work  with  in 
subsequent  dBASE  IV  transactions. 

Examples 

To  SAVE  all  memory  variables  to  the  disk  file,  Myfile.mem,  located  on  disk 
drive  B: 

.  SAVE  TO  B:fyfiLe 

To  SAVE  all  memory  variables  with  names  beginning  with  the  letter  d  to  the 
disk  file,  Myfile.mem,  located  on  disk  drive  B: 

.  SAVE  ALL  LIKE  d*  TO  B:fyfile 

To  SAVE  all  memory  variables,  except  those  with  names  containing  the  letter 
x  as  the  fourth  character,  to  the  disk  file,  Myfile.old,  on  the  default  drive: 

.  SAVE  ALL  EXCEPT???*  TO  fyfiLe.oLd 

See  Also 

PARAMETERS,  PRIVATE,  PUBLIC,  RESTORE,  SET  SAFETY,  STORE 
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SAVE  MACROS 


SAVE  MACROS  lets  you  save  the  currently  defined  macros  from  memory  to  a 
disk  file.  You  can  restore  the  macro  file  to  memory  any  time  you  want  to  use 
that  set  of  macro  definitions. 


Syntax 

SAVE  MACROS  TO  <  macro  file  > 


Usage 

Use  this  command  to  create  a  file  with  the  default  extension  .mcr.  You  may 
define  macro  keys  A^f-FI  through  A^T-F9,  and  also  Ajff-FlO  followed  by  the 
letters  A  through  Z.  Therefore,  there  are  35  unique  macro  keys. 

You  may  save  a  minimum  of  one  and  a  maximum  of  35  macro  definitions  to 
each  file. 

Before  you  can  overwrite  an  existing  macro  file,  if  SET  SAFETY  is  ON,  a 
message  alerts  you  to  the  existence  of  a  file  with  the  same  name. 

You  may  specify  an  extension  other  than  .mcr;  but  remember  to  use  that 
special  extension  with  the  filename  when  restoring  the  file. 


NOTE 

The  .mac  extension  is  used  by  the  dBASE  IV  Applications  Generator 
program.  Do  not  use  the  .mac  extension  for  your  macro  files. 


Example 

.  fVOVS  TO  fecdsrrv 

This  command  creates  a  macro  file  called  Macdemo.mcr,  and  saves  the 
current  macro  definitions  to  it. 


See  Also 

PLAY  MACRO,  RESTORE  MACROS 
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SAVE  WINDOW 


The  SAVE  WINDOW  command  saves  window  definitions  to  a  disk  file. 

Syntax 

SAVE  WINDOW  <  window  name  list >  /ALL  TO  <  filename  > 


Usage 

This  command  creates  the  disk  file  you  name,  and  saves  the  windows  listed 
in  <  window  name  list >  ,  or  all  windows  in  memory,  to  this  file.  Only  win¬ 
dows  that  are  defined  and  currently  in  memory  can  be  saved  to  disk. 

The  SAVE  WINDOW  command  overwrites  an  existing  disk  file  if  you  use  the 
same  file  name.  SET  SAFETY  ON  first,  and  you  will  get  a  prompt  before  the 
file  is  overwritten. 

The  default  extension  for  the  output  disk  file  is  .win.  If  you  assign  a  different 
^tension  to  the  window  definition  file,  then  specify  this  extension  with  the 
filename  to  the  RESTORE  WINDOW  command. 

If  you  specify  ALL,  all  the  windows  in  memory  are  saved  to  the  disk  file. 


See  Also 

DEFINE  WINDOW,  RESTORE  WINDOW 
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The  SCAN  command  is  a  simplified  alternative  to  the  DO  WHILE  command. 
SCAN  offers  a  more  natural  syntax  for  automatically  selecting  records  from  a 
data  file,  and  for  applying  processing  commands  to  those  records. 

Syntax 

SCAN  [<  scope  >  ]  [FOR  <  condition  >  ]  [WHILE  <  condition  >  ] 

[<  commands>  ...] 

[LOOP] 

<  commands> 

[EXIT] 

<  commands  > 

ENDS  CAN 

Usage 

SCAN  cycles  through  an  active  data  file,  acting  on  records  that  fall  within  the 

<  scope  >  ,  and  on  records  that  meet  the  FOR  and  WHILE  conditions.  The 
commands  you  place  between  SCAN  and  ENDSCAN  provide  the  processing 
for  the  records  selected. 

The  <  scope  >  option’s  default  is  every  record  in  the  file,  starting  from  the 
beginning  of  the  file.  If  you  use  NEXT  or  RECORD  for  the  <  scope  >  ,  scan¬ 
ning  begins  at  the  current  record. 

The  FOR  <  condition  >  specifies  which  records  within  the  <  scope  > 
should  be  acted  on. 

The  WHILE  <  condition  >  further  limits  the  records  that  may  be  acted  on, 
allowing  processing  only  as  long  as  the  WHILE  conditional  expression 
remains  true  (.T.). 

LOOP  returns  control  to  the  beginning  of  the  SCAN  process. 

EXIT  ends  a  SCAN  process.  Control  goes  to  the  next  command  following 
ENDSCAN. 

Record  Pointer 

SCAN  has  specific  effects  on  the  record  pointer.  A  SCAN  begins  at  the  begin¬ 
ning  of  a  file,  unless  you  instruct  otherwise  through  the  <  scope  >  ,  or 
through  the  FOR  and  WHILE  conditions.  A  SCAN  continues  to  the  end  of  a 
file,  unless  the  <  scope  >  ,  the  FOR  or  WHILE  conditions,  or  the  EXIT 
option  end  processing  sooner.  The  record  pointer  remains  where  it  was 
when  processing  ended. 
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SCAN 


Examples 

This  simple  SCAN  example  executes  a  procedure  that  does  backorders  for 
each  uninvoiced  record  in  the  Transact  data  file: 


USE  Transact 

SCPN  FOR  .NOT.  Invoiced 

DO  Badcordr  WITH  Order Jd,  Clientjd,  DateJrans 
BDSCAN 


Accomplishing/^ ith  DO  WHIL^the  same  effect  as  the  above  SCAN  example^ 
requires  this  code:  ^ - - - ^ 


USE  Transact 

LOCATE  FCR  .NOT.  Invoiced 
DO  WHILE  .NOT.  BDFO 

DO  SBckordr  WITH  Orderjd,  ClientJd,  DateJrans 
CCNTINLE 
BCOO 


See  Also 

CONTINUE,  LOCATE 
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SEEK  searches  for  the  first  record  in  an  indexed  database  file  with  a  key  that 
matches  a  specified  expression.  SEEK  conducts  a  very  rapid  record  search. 

Syntax 

SEEK  <  exp> 


You  normally  use  SEEK  with  memory  variables.  The  specified  expression 
used  by  SEEK,  however,  must  be  a  valid  dBASE  IV  expression  and  must 
have  the  same  data  type  as  the  index  key  expression. 

Substring  or  partial  key  searches  work  only  if  the  search  expression  matches 
the  index  key,  starting  with  the  character  on  the  far  left.  The  criteria  for  the 
search  also  depend  on  the  setting  of  SET  EXACT. 


For  example,  if  the  index  key  is  Smith,  John  with  SET  EXA3T  OFF,  5m/ will 
find  the  index  key.  However,  if  SET  EXACT  is  ON,  the  search  expression 
would  have  to  match  the  full  length  of  the  index  key,  which  in  this  example 
would  be  Smith,  John. 


Record  Pointer 

If  the  search  is  unsuccessful,  the  message  Find  not  successful  appears,  and 
the  record  pointer  moves  to  the  end  of  the  file  (EOF()  is  T.).  Use  SET  TALK 
OFF  to  suppress  the  message. 

If  you  have  SET  NEAR  ON,  and  your  SEEK  is  not  successful,  the  record 
pointer  is  positioned  to  the  record  whose  index  key  immediately  follows  that 
of  the  sought-for  key. 

The  FOUND()  function  is  set  to  true  (.T.)  when  the  SEEK  is  successful  and 
the  record  pointer  is  set  to  the  found  record. 


Example 

The  Transact  database  file  is  used  to  demonstrate  this  command. 


To  SEEK  a  date  <  expression  >  : 

.  USE  Transact  ORDER  Recent 
.  SEBC<JXAJl/m 

.  ?  Client-id,  Invoiced,  TotaLbill 
cmn  .f.  i65.oo 
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SEEK 


See  Also 

CONTINUE,  EOF(),  FIND,  FOUND(),  INDEX,  KEY(),  LOCATE,  MDX(), 
NDX(),  SET  DELETED,  SET  EXACT,  SET  INDEX,  SET  NEAR,  SET  ORDER, 
TAG(),  USE 
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SELECT 


Use  SELECT  to  choose  a  work  area  in  which  to  open  a  database  file,  or  to 
specify  a  work  area  in  which  a  database  file  is  already  open. 


Syntax 

SELECT  <  work  area  name/alias  name> 


Usage 

When  you  enter  dBASE  IV,  the  active  work  area  is  work  area  1.  The  valid 
work  areas  are  1  through  10,  or  A  through  J.  You  can  open  a  database  file  in 
each  work  area  you  select.  Work  area  10  is  reserved  for  an  open  catalog.  You 
cannot  open  a  database  file  in  this  area  if  a  catalog  is  open.  If  you  have  a 
database  file  open  in  work  area  10  and  then  open  a  catalog,  your  database 
file  will  be  closed  automatically.  Anytime  you  open  a  file  in  a  work  area  con¬ 
taining  an  open  database  file,  the  first  file  is  closed. 

Each  work  area  is  also  used  for  opening  other  files  associated  with  the  data¬ 
base  file;  for  example,  index,  query,  and  format  files.  However,  the  same 
associated  files  cannot  be  open  in  more  than  one  work  area  at  the  same 
time. 

You  can  use  SELECT  to  change  work  areas  so  that  the  database  file  open  in 
the  selected  work  area  becomes  the  active  database  file.  You  can  change  the 
current  work  area  by  specifying  the  alias  of  the  database  file  open  in  another 
work  area  or  the  work  area  number  or  letter.  If  you  do  not  specify  an  alias 
when  you  open  the  file,  the  filename  (without  the  extension)  is  the  default 
alias  name. 

To  use  a  variable  to  select  a  work  area  or  its  alias,  the  variable  must  be  pre¬ 
ceded  by  the  macro  (&)  function.  For  example,  if  the  alias  name  is  stored  in 
a  character  memory  variable  M_ alias,  type  SELECT  <SPM_alias. 

Normally,  commands  display  or  change  the  contents  of  fields  in  the  active 
database  file.  However,  you  can  specify  fields  in  other  work  areas  by  using 
an  alias. 

If  you  have  issued  the  SET  FIELDS  command,  and  SET  FIELDS  is  ON,  you 
can  also  display  or  change  data  for  the  fields  in  the  specified  FIELDS  list  in 
other  work  areas. 

Record  Pointer 

Each  work  area  maintains  a  separate  record  pointer.  Moving  between  work 
areas  does  not  affect  the  position  of  any  record  pointer. 
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SELECT 


Examples 

la  this  example,  the  Customer  database  file  is  opened  in  work  area  1,  and 
the  Transact  database  Hie  is  opened  in  work  area  3: 

.  SELECT  1 

.  USE  Qjstxmr  ALIAS  Names 
.  SELECT  3 
.  USE  Transact 

To  change  the  work  area,  SELECT  the  alias  of  the  file  or  the  number  or  letter 
of  the  work  area: 

c  SELECT  Hames 

In  these  examples,  work  areas  were  selected  by  using  a  work  area  number 
and  the  alias  name  of  a  database  file  open  in  a  work  area.  You  could  also 
select  a  work  area  by  a  letter  (for  example,  selecting  work  area  1  by  entering 
SELECT  A). 

See  Also 

ALIAS(),  CLOSE,  CONTINUE,  LOCATE,  SET  CAIALOG,  SET  HELDS, 

SET  VIEW,  USE 
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SHOW  MENU 


I 

SHOW  MENU  displays  a  bar  menu  without  activating  it. 

Syntax 

SHOW  MENU  <  menu  name>  [PAD  <  pad  name>  ] 

Usage 

This  command  displays  on  the  screen,  over  any  existing  display,  the  menu 
named  in  the  command. 

If  you  display  a  bar  menu  with  the  SHOW  MENU  command,  you  cannot 
move  the  cursor  in  it  or  make  selections  from  it.  Use  this  command  in  pro¬ 
gram  development  to  check  the  screen  appearance  of  a  menu  you  are 
designing. 

See  Also 

ACTIVATE  MENU,  DEFINE  MENU 


ii 


I! 
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SHOW  POPUP 


The  SHOW  POPUP  command  displays  a  popup  without  activating  it. 

Syntax 

SHOW  POPUP  <  popup  name> 

Usage 

Use  this  command  to  display  a  pop-up  menu  without  activating  it.  This 
feature  is  useful  in  program  development. 

Because  the  pop-up  menu  is  not  active,  the  cursor  cannot  be  moved  around 
in  it  and  messages  associated  with  the  pop-up  menu  are  not  displayed.  The 
cursor  remains  at  the  dot  prompt. 


Example 

To  display  the  View.pop  pop-up  menu: 

.  SHCU  PCRP  Viacpcp 

The  View_pop  menu  is  displayed.  Use  the  CLEAR  command  to  erase  the 
pop-up  menu  from  the  screen. 


See  Also 

ACTIVATE  POPUP,  DEFINE  BAR,  DEFINE  POPUP,  POPUPQ 
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SKIP  moves  the  record  pointer  forward  or  backward  in  a  database  file. 


Syntax 

SKIP  [<  expN>  ]  [IN  <  alias  name>  ] 


Usage 

If  the  database  file  is  INDEXed,  SKIP  follows  the  index  record  order.  If  the 
file  is  not  indexed,  the  record  pointer  moves  sequentially  by  record  number. 

The  record  pointer  moves  forward  through  the  records  of  the  database  file, 
from  the  current  record  to  the  end  of  the  file,  unless  the  result  of  the 
numeric  expression  is  negative.  A  negative  expression  moves  the  record 
pointer  from  the  current  record  toward  the  beginning  of  the  file.  If  the 
expression  is  not  included,  dBASE  IV  moves  forward  one  record. 

If  you  specify  IN  <  alias  name>  ,  SKIP  moves  the  record  pointer  of  the 
work  area  designated  by  the  alias  name.  The  record  pointer  in  the  original 
work  area  is  not  affected.  If  SET  TALK  is  ON,  the  name  of  the  database  file 
precedes  the  record  number  in  the  display. 


Record  Pointer 

If  you  issue  SKIP  when  the  record  pointer  is  on  the  last  record  in  a  file,  the 
value  of  RECNO()  is  one  greater  than  the  number  of  records  in  the  file,  and 
EOF()  is  true  (.T.). 

If  you  issue  SKIP  —  1  when  the  record  pointer  is  on  the  first  record, 
RECNO()  remains  at  1;  BOF(),  however,  is  true,  which  indicates  that  the 
record  pointer  is  at  the  beginning  of  the  file. 

Special  Cases 

Because  SKIP  follows  the  index  order  if  an  index  is  active,  you  should  be 
especially  careful  when  SKIPping  through  records  of  an  indexed  database 
file  in  a  network  environment.  If  one  user  edits  a  field  that  is  part  of  the 
index  key,  or  appends  records  to  the  database  file,  all  records  in  the  file  will 
be  reordered  after  the  change  is  saved.  An  attempt  to  SKIP  to  or  past  a 
newly  appended  or  changed  record  returns  different  results  than  if  no 
change  or  addition  has  been  made. 
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If  another  user  APPENDS  a  record,  for  example,  and  you  attempt  to  position 
on  that  new  record  with  a  SKIP,  the  record  pointer  will  indicate  the  end  of 
file  and  EOF()  will  be  true.  If  another  user  edits  a  key  field  in  a  record,  and 
you  attempt  to  position  past  that  record,  the  record  pointer  wil  indicate  a 
different  record  than  if  the  key  field  has  not  been  changed. 

To  compensate  for  these  changes  in  a  network  environment,  you  may  issue  a 
GO  RECNO()  command  to  reposition  the  record  pointer  on  the  current 
record,  and  then  issue  the  SKIP  command. 


Examples 

The  database  files  Client  and  IVansact  are  used  in  these  examples. 
To  move  forward  one  record  in  the  database  file: 

.  USE  Client 
.  SKIP 

CUBIT:  Record  to  2 


To  move  forward  five  records,  using  a  numeric  memory  variable: 
.  Mskip  -5 

5.00 

c  SOP  Mskip 

CUBIT:  Record  to  7 


To  move  the  record  pointer  in  the  Transact  database  file  while  Qient  is  the 
currently  selected  file: 

.  USE  Transact  IN  2 
.  SOP  4  IN  Transact 
TRANSACT:  Record  to  5 


See  Also 

BOF(),  EOF(),  GO/  GOTO,  RECNO() 
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SORT  creates  a  new  database  file  in  which  the  records  of  the  active  database 
file  are  positioned  in  the  ASCII  order  of  the  specified  key  fields. 


Syntax 

SORTTO  <  filename  >  ON  <  field  1  >  [/A]  [/C]  [/D] 

[,<  field2 >  [/A]  [/ C]  [/D]  ...]  [ASCENDING]/ [DESCENDING] 
[<  scope  >  ]  [FOR  <  condition  >  ]  [WHILE  <  condition  >  ] 


Defaults 

SORTs  are  in  ascending  order  (/A)  unless  you  state  /D  or  DESCENDING 
Ascending  order  is  the  same  as  ASCII  order  (refer  to  Appendix  G). 

SORT  updates  a  catalog  if  one  is  in  use. 


Usage 

You  may  not  SORT  logical  or  memo  fields. 

You  can  SORT  on  a  maximum  often  fields. 

A  file  cannot  be  SORTed  to  itself  or  to  any  other  open  file. 

Options 

/ C  causes  the  SORT  not  to  differentiate  between  upper  and  lower  case. 
Therefore,  / C  creates  a  file  that  is  not  in  strict  ASCII  order. 

/A  and  /D  apply  only  to  one  field.  You  may  combine  /C  with  either  /A or  /D. 
When  using  two  options,  include  only  one  slash  (for  example,  /DC). 

ASCENDING  and  DESCENDING  affect  all  fields  that  do  not  have  an  /A  or  /D 
option.  /  A  or  /D  overrides  the  ASCENDING  or  DESCENDING  options,  but 
only  for  the  field  names  preceding  the  /A or  /D  symbol. 


Tips 

SORT  and  INDEX  both  reorder  the  records  in  a  database  file.  SORT  creates 
a  new  physical  database  file  that  is  written  on  disk;  INDEX  creates  an  index 
(.ndx)  file  or  multiple  index  (.mdx)  file  tag  that  contains  pointers  to  each 
record  in  the  original  file,  but  does  not  physically  rearrange  the  original 
database  file.  You  may  think  of  a  SORT  operation  as  analogous  to  an  INDEX 
command  followed  by  a  COPY. 
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These  commands: 

o  INDEX  CN  Lastname  TO  Lrarn 
.  COPT  TO  Namfile 

perform  an  operation  similar  to 

c  SORT  CN  Lastname  TO  temcfile 

SORT  rearranges  the  records  in  ASCII  order,  however,  and  INDEX  creates 
pointers  in  alphabetic  order. 

SORT  does  not  work  with  substrings  or  other  expressions.  Use  INDEX  to 
designate  keys  that  cannot  be  SORTed,  and  then  COPY  to  create  a  sorted  file. 

Based  on  your  application,  you  may  decide  that  physically  rearranging  the 
data  with  a  SORT  is  preferable  at  some  times,  and  that  CREATEing  an  index 
with  pointers  back  to  the  original  data  records,  without  re-writing  the  data¬ 
base  file  to  disk,  is  preferable  at  others.  TWo  additional  factors  may  influence 
your  decision: 

■  The  FIND  and  SEEK  commands  work  only  with  INDEXed  files,  not  with 
SORTfed  files.  If  you  plan  to  search  the  database  file  for  records  or  fields 
that  match  a  specified  value,  use  INDEX. 

■  INDEX  and  SORT  each  provide  a  different  set  of  options.  For  example, 
you  can  INDEX  a  file  with  the  UNIQUE  option,  so  that  only  the  first 
record  of  several  records  with  the  same  key  value  are  entered  into  the 
index.  You  can  also  index  on  an  expression,  including  the  substring  of  a 
character  field.  On  the  ( ther  hand,  the  SORT  command  allows  you  to 
use  the  FOR  and  WHILE  clauses  to  extract  a  subset  of  the  original  data¬ 
base  file.  SORT  also  allows  you  to  specify  that  only  one  field  should  be  in 
reverse  order,  while  INDEX  requires  that  the  entire  expression,  includ¬ 
ing  all  fields,  be  descending.  Check  the  options  for  INDEX  and  SORT  to 
see  which  command  is  more  useful  in  your  application. 

Do  not  use  the  letters  A  through  J,  or  the  letter  M,  as  database  filenames, 
because  they  are  reserved  for  default  alias  names.  AA,  however,  is  a  valid 
database  filename. 

When  SORTing  on  multiple  fields,  place  the  most  important  key  first. 
Separate  the  field  names  with  commas. 
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Example 

Tb  create  a  new  database  file  called  Byclient  from  the  TVansact  database, 
sorted  on  Client. id  in  reverse  chronological  order: 

,  .  USE  Transact 

SORT  CN  CL  ientJd/A,  Oatc_Jrans/D  TO  Bycl  ient 
1QK  Sorted  12  Records  sorted 


z’s/s  £/?  r 


.  USE  BycL  ient 
LIST 


BKUBIT:  Record  hb 


■dtt 

CLIENLJD 

CRD6RJD 

UATEJTVNS 

INDUCED 

TOTALBILL 

1 

pans 

87-113 

03/24/87 

.T. 

is.m 

2 

A100S 

87-116 

04/10/87 

.F. 

ism.m 

3 

Aims 

87-105 

02/03/87 

.T. 

185D.m 

4 

B12CC0 

87-114 

03/30/87 

.F. 

45D.m 

5 

conn 

87-115 

04/01/87 

.F. 

i<55.m 

6 

coomi 

87-10B 

02/23/87 

.T. 

1250.m 

7 

ccmm 

87-105 

02/10/87 

.T. 

i2m.m 

8 

rfTTTP 

87-110 

05/09/87 

.T. 

i75.m 

9 

cans 

87-107 

02/12/87 

.T. 

1230.m 

10 

LdEDI 

87-112 

03/20/ 87 

.T. 

700.00 

11 

LQ3D1 

87—109 

03/09/87 

.T. 

415.00 

12 

inmn? 

87-111 

03/11/87 

.F. 

10CD.00 

See  Also 

COPY,  INDEX 


/lr  //^s£/ir 
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STORE 


STORE  creates  and  initializes  one  or  more  memory  variables,  and  initializes 
array  elements  previously  created  with  the  DECLARE  command. 

Syntax 

STORE  <  expression  >  TO  <  memvar  list>  /<  array  element  list> 

An  alternative  syntax  for  STORE  is: 

<  memvar>  /<  array  element>  =*  <  expression  > 


Defaults 

The  number  of  memory  variables  you  can  have  is  the  product  of  the 
MVBLKSIZE  and  MVMAXBLKS  settings,  which  are  contained  in  the 
Config.db  file.  If  MVBLKSIZE  =  50  and  MVMAXBLKS  -  10  (the  default 
settings),  you  can  STORE  up  to  500  memory  variables. 

Each  array  that  you  DECLARE  takes  only  one  memory  variable  slot.  A 
special  block  is  allocated  for  each  array  to  hold  the  elements.  Therefore,  the 
number  of  array  elements  do  not  take  away  from  the  number  of  slots  initial¬ 
ized  by  MVBLKSIZE  and  MVMAXBLKS. 

Usage 

The  data  type  of  the  variable  or  element  is  determined  by  the  expression 
STOREd.  For  example: 

.  STORE  36525  7  V  Hyear 

creates  a  fixed  point  numeric  variable  called  N_year.  All  numeric  variables 
created  from  constants,  such  as  365.25,  are  in  Binary  Coded  Decimal  format, 
unless  the  FLOAT()  function  converts  the  value  to  floating  point  binary. 

An  expression  may  be  stored  to  several  memory  variables  or  array  elements 
with  a  single  STORE  command.  You  may  mix  elements  and  memory  vari¬ 
ables  in  the  same  STORE  statement,  such  as: 

.  STORE  1  to  H_n1,  Ht2,  cneC1,1J 

With  the  alternate  syntax,  <  memvar>  /<  array  element>  *» 

<  expression  >  ,  you  may  store  an  expression  only  to  one  memory  variable 
or  one  array  element  at  a  time,  the  expression  must  be  on  the  right  side  of 
the  equal  sign,  and  the  memory  variable  name  cannot  be  the  same  as  a 
dBASE  IV  command. 
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If  a  memory  variable  or  array  of  the  same  name  already  exists,  it  is  overwrit¬ 
ten,  unless  one  variable  or  array  is  declared  PUBLIC  and  the  other  PRIVATE. 

Memory  variable  and  array  element  names  may  contain  letters,  numbers, 
and  underscores.  The  name  may  be  up  to  10  characters  long,  but  must  not 
begin  with  a  number  or  underscore.  Single-character  names  are  permitted, 
but  you  should  not  use  the  single  letters  A  through  J,  or  the  letter  M,  to 
name  variables  because  these  may  conflict  with  alias  names.  Double  letter 
combinations,  such  as  AA,  are  acceptable. 


Tips 

If  a  memory  variable  returns  an  unexpected  value,  there  may  be  a  field  with 
the  same  name  in  an  active  database  file. 

A  field  with  the  same  name  as  a  memory  variable  takes  precedence  in  all 
operations  except  with  macro  substitution  (&).  To  explicitly  declare  that  the 
memory  variable  takes  precedence,  use  M->  (the  symbol  used  to  specify  a 
memory  variable)  before  the  variable  name,  as: 

M->  <  memvar> 

You  may  choose  to  begin  variable  names  with  a  distinguishing  letter  or  let¬ 
ters,  such  as  AL,  so  that  they  will  not  be  confused  with  field  names.  This  will 
also  allow  you  to  RELEASE  or  SAVE  sets  of  variables  and  leave  others  intact. 
For  example: 


.  RELEASE*!.  UKE  H*  8&7his  rel« 


»  all  variables  begiming  with  "flj . 


.  SAt€  TV  Holdnen  ALL  LIKE  A-*  SffThis  creates  a  file  called  rtoldnenumem,  and  « 
all  variables  begiming  with  "M  to  it. 


Special  Cases 

Data  types  follow  certain  rules  of  concordance: 

■  A  numeric  variable  or  element  (either  type  N  or  type  F)  may  operate  on 
itself,  or  on  another  numeric  or  date  variable,  element,  or  field. 

■  A  character  variable  or  element  may  be  concatenated  to  itself,  or  to 
another  character  memory  variable,  element,  or  field.  It  may  also  be 
concatenated  with  the  substring  of  a  memo  field. 

■  A  date  variable  or  element  may  operate  on  itself,  or  on  another  date  or 
numeric  memory  variable,  element,  or  field. 

■  A  logical  variable  or  element  may  not  be  concatenated  or  added  to  itself, 
another  logical  memory  variable  or  field,  or  any  other  variable,  element, 
or  field.  You  may  join  logical  variables  with  Boolean  operators. 
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Any  attempt  to  combine  data  types  that  violates  these  rules  will  result  in  a 
Data  type  mismatch  error  message.  You  may  use  certain  data  conversion 
functions  to  convert  variables  and  elements  to  a  compatible  data  type. 


Examples 

To  create  a  logical  memory  variable  L_paid,  and  initialize  it  to  false  (  F.): 

.  STCRE  .F.  TV  Lpaid 
.F. 

To  create  a  floating  point  binary  numeric  variable: 

.  F_year  =  FLOAT 065 £5) 

To  initialize  the  memory  variables  Mcostl,  Mcost2,  and  Mcost3  to  zero: 

.  STCRE  0  TV  Mccstl,  Moost2,  HxstJ 

To  initialize  array  elements  Month[l,2],  Month[2,2],  and  Month[3,2]  with  the 
character  strings  January,  February,  and  March,  respectively: 

.  DECLARE  NcnthC3s2J 
.  ftnthCl^ZJ  -  "January 
JanLBry 

„  MyithC2^2J  =  "Fetnary 
February 

.  HnthCS^J  =  " fibred" 

March 


You  may  create  date  variables  with  curly  braces  ({}): 

.  fi/eurmth  =  {L7/OT/88} 

07/01/88 

.  Lastmnth  =  Neunnth  -  1 
06/10/8$ 


See  Also 

&,  CLEAR  ALL,  CLEAR  MEMORY,  DECLARE,  LIST/DISPLAY  MEMORY, 
PARAMETERS,  PRIVATE,  PUBLIC,  RELEASE,  RESTORE,  SAVE 
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SUM 


SUM  totals  numeric  expressions  to  memory  variables  or  arrays. 

Syntax 

SUM  [  <  expN  list  >  ]  [TO  <  memvar  list  >  /TO  ARRAY  <  array  name  >  ] 
[<  scope  >  ]  [FOR  <  condition  >  ]  [WHILE  <  condition  >  ] 


Defaults 

Unless  otherwise  specified  by  a  scope  or  a  FOR  or  WHILE  clause,  all  data¬ 
base  records  are  SUMmed. 

If  you  do  not  provide  an  expression  list,  all  numeric  fields  are  SUMmed. 

Usage 

The  sum  for  each  numeric  expression  is  placed  in  the  memory  variable  list 
or  array.  The  sum  of  the  first  expression  is  placed  in  the  first  variable  of  the 
list  or  first  array  element,  and  processing  continues  for  each  item  in  the 
expression  list.  If  there  are  insufficient  memory  variables  or  elements  in  the 
array,  only  the  existing  variables  or  elements  are  filled.  If  there  are  more 
variables  in  the  list  or  more  array  elements  than  needed,  the  extra  variables 
or  elements  will  not  be  filled  and  will  contain  their  original  values. 

The  named  array  must  be  one-dimensional.  SUM  produces  a  type  F  numeric 
variable. 


Example 

To  sum  the  Total.cost  and  Qty  fields  to  the  array  Mitems: 

.  USE  Stock 
.  DECLARE  MitemsCZJ 
.  SLM  ItenLpost >  Qty  70  ARRAY  Mitems 
STOCK:  Record  No  1 

Item_cost  Qty 

10505.00  23.00 

.  ?  STRCMitmsCZJ^JDs  ’ pieces  * ere  sold  to  cbte 
20  pieces  were  sold  to  date. 

.  ?  'The  sun  of  the  totals  is  T  +  L TTUMCSTRCMi temsC1J^9^2)) 
The  sun  of  the  totals  is  $10505.00 


See  Also 

AVERAGE,  CALCULATE,  DECLARE,  FIXEDQ,  FLOATQ,  STORE,  TOTAL 
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SUSPEND 


SUSPEND  is  a  debugging  command  that  lets  you  stop  a  program  while  it  is 
executing.  You  can  then  enter  commands  from  the  keyboard  or  the  history 
buffer,  and  RESUME  the  program. 

Syntax 

SUSPEND 


You  can  suspend  execution  by  placing  the  SUSPEND  command  within  a 
program,  or  by  typing  S  at  the  ACTION:  prompt  in  the  debugger. 

If  SET  TRAP  is  OFF  and  you  press  the  Esc  key  while  a  program  is  running, 
dBASE  IV  prompts  Cancel  Ignore  Suspend.  If  you  press  Esc  when  SET 
TRAP  is  ON,  dBASE  IV  presents  the  debugger  screen. 

If  you  respond  with  Suspend,  you  can  either  change  a  dot  prompt  command 
line  stored  in  the  history  buffer  or  execute  new  commands.  Commands  from 
program  files  are  not  stored  in  the  history  buffer.  You  cannot  modify  the 
SUSPENDed  dBASE  program  file  or  other  open  dBASE  program  or  proce¬ 
dure  files.  If  you  try,  dBASE  IV  responds  with  File  already  open.  You  can, 
however,  modify  the  file  if  you  are  executing  it  from  within  the  debug 
screen. 

When  you  are  ready  to  continue  program  execution,  type  RESUME 

If  you  create  any  memory  variables  while  the  file  is  suspended,  they  are 
PRIVATE  at  the  level  of  the  suspension. 

CANCEL  cancels  all  DO  files,  including  ones  that  are  suspended.  You  must 
close  any  procedure  file  with  CLOSE  PROCEDURE.  RETURN  closes  the 
most  recently  opened  DO  file. 

If  you  attempt  to  return  to  the  program  by  typing  DO  <  filename  >  at  the 
dot  prompt  while  the  program  is  suspended,  you  may  eventually  run  out  of 
memory.  Use  RESUME  to  continue  execution  of  the  program,  rather  than 
running  the  program  again  from  the  beginning.  Use  CANCEL  to  close  all 
open  program  files. 


See  Also 

CANCEL,  COMPILE,  DEBUG,  DO,  RESUME,  RETURN,  SET  ECHO, 
SET  PROCEDURE,  SET  STEP,  SET  TALK,  SET  TRAP 


2-246 


COMMANDS 


PAGE:  247  SESS:  7 


U*d  Hay  11  16:  32:  00  1388 
sk2/ a  I  I J  obz/CLS_manha  t  /GRP_manha  t  /  JOB_n»an  I  angra  f  /O I  V_ I  r chap2  f 


TEXT 


TEXT  outputs  blocks  of  text  to  the  screen  or  printer.  This  command  provides 
a  simple,  convenient  way  to  write  to  the  output  device. 

Syntax 

TEXT  <  text  characters  >  ENDTEXT 


Usage 

The  text  characters  are  output  exactly  as  originally  entered  into  a  program. 

The  &  (macro)  function  is  not  expanded  when  embedded  in  the  text,  and  is 
output  exactly  as  typed. 


SET  PRINTER  ON  to  send  text  to  the  printer. 


Example 

The  following  two  sentences  of  text  are  displayed  on  the  screen  if  this 
TEXT... ENDTEXT  block  is  contained  in  a  program: 

TEXT 

This  is  an  example  of  text  that  is  to  be  displayed  by  the 
TEXT  conrend.  This  text  is  routed  directly  to  toe  screen 
without  being  interpreted  by  cfiASE  IV. 

BDTEXT 


SEE  ALSO 

@,  ?/??,  ???,  UST/DISPLAy,  SET  PRINTER 
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TOTAL 


TOTAL  sums  the  numeric  fields  of  the  active  database  file  and  creates  a 
second  database  file  to  hold  the  results.  The  numeric  fields  in  the  TO  data¬ 
base  file  contain  the  totals  for  all  records  that  have  the  same  key  value  in  the 
original  database. 


Syntax 

TOTAL  ON  <  key  field  >  TO  <  filename  >  [FIELDS  <  fields  list  >  ] 
[<  scope  >  ]  [FOR  <  condition  >  ]  [WHILE  <  condition  >  ] 


Defaults 

The  TO  filename  must  include  the  drive  designator  if  it  is  not  on  the  default 
drive.  dBASE  IV  assumes  a  .dbf  extension  unless  you  specify  otherwise. 

Unless  otherwise  specified  by  the  scope,  or  a  FOR  or  WHILE  clause,  all 
records  are  TOTALed.  All  numeric  fields  in  the  record  are  totalled  unless 
limited  by  the  FIELDS  list. 

If  a  catalog  is  in  use,  the  TO  file  is  added  to  it. 

Usage 

The  active  database  file  must  be  either  INDEXED  or  SORTfed  on  the  key 
field.  If  the  TO  filename  exists,  TOTAL  gives  a  warning  prompt  before  over¬ 
writing  the  file,  unless  SET  SAFETY  is  OFF. 

All  records  with  the  same  key  field  become  a  single  record  in  the  TO  data¬ 
base.  All  numeric  fields  appearing  in  the  FIELDS  list  contain  totals.  All  other 
fields  contain  the  data  from  the  first  record  of  the  set  of  records  with  identi¬ 
cal  keys. 

The  structure  of  the  TO  file  is  the  same  as  the  active  database  file’s,  except 
that  memo  fields  are  not  copied  to  the  new  file.  "type  N  numeric  fields  in  the 
source  file  produce  type  N  numeric  totals  in  the  TO  file,  and  type  F  fields 
produce  type  F  totals. 


Tips 

Do  not  use  the  single  letters  A  through  J,  or  the  letter  M,  as  database 
filenames,  because  they  are  reserved  for  default  alias  names.  AA,  however, 
is  a  valid  database  filename. 

If  a  field  size  in  the  TO  file  is  not  large  enough  to  accommodate  the  total, 
dBASE  IV  places  asterisks  in  the  field  (indicating  an  overflow).  To  avoid  this, 
use  MODIFY  STRUCTURE  to  increase  the  size  of  the  fields  in  the  active  data¬ 
base  file  to  a  size  that  can  handle  the  largest  total. 
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TOTAL 


Example 

To  create  a  new  database  file  called  Amounts  from  the  TVansact  database  file, 
with  the  sum  of’Ibtal.bill  for  each  Client. id: 

.  LSE  Transact  ORDER  Cl  ientjd 
tester  index:  CUBIT-ID 

.  TOTAL  CN  Cl  ientu'd  TO  Amounts 
12  records  totaled 
7  records  generated 


.  USE  Amounts 

>*.  LIST  Client-id,  TotaU»ill 


AMDLNTS:  Record  No  1 
Record#  CUBIUD  TOTALBILL 


1  tfUIE  125.00 

2  A1CD25  3350.00 

3  B1200D  450.00 

4  (mm  2615.00 

5  ffTTTP  1425.00 

6  L00001  1115.00 

7  inmrp  1000.00 


See  Also 

AVERAGE,  INDEX,  MODIFY  STRUCTURE,  SET  SAFETY,  SORT,  SUM 
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TYPE 


TYPE  displays  the  contents  of  an  ASCII  text  file. 


Syntax 

TYPE  <  filename >  [NUMBER]  [TO  PRINTER/TO  FILE  <  fllename>  ] 


Defaults 

The  filename  must  include  the  file  extension.  If  the  file  is  not  on  the  default 
drive,  and  SET  PATH  is  not  set  to  the  file’s  location,  you  must  precede  the 
filename  with  its  drive  and  directory  location. 

Files  with  extended  ASCII  characters  are  displayed  as  graphic  characters. 

Usage 

TYPE  displays  standard  ASCII  text  files  only,  such  as  command  or  procedure 
files.  TYPEd  database  files,  index  files,  and  database  text  files  cannot  be  eas¬ 
ily  read  because  they  contain  other  information  that  dBASE  IV  uses.  TYPE 
cannot  specify  an  open  file;  in  other  words,  a  program  may  not  include  a 
command  to  TYPE  itself  or  any  other  open  file. 


Options 

If  you  include  the  NUMBER  keyword  in  the  command,  line  numbers  will  be 
displayed  or  printed.  Line  lumbers  correspond  to  the  physical  lines  in  the 
program,  not  lines  in  the  display.  Line  continuations  in  the  program  count  as 
separate  lines.  A  page  heading  consisting  of  the  filename,  the  date,  and  the 
page  number  is  also  displayed  unless  SET  HEADING  is  OFF.  The  complete 
filename  as  entered  on  the  command  line  is  displayed  on  the  left,  followed 
by  the  current  date  in  the  SET  DATE  format.  Page  numbers  are  displayed  on 
the  right  of  the  page. 

If  you  include  TO  PRINTER,  the  output  will  be  sent  to  the  printer.  If  you 
include  TO  FILE  <  filename >  ,  the  output  will  be  written  to  a  disk  file  with 
the  specified  filename.  You  may,  for  example,  create  another  disk  file  that 
includes  line  numbers. 

See  Also 

SET  DATE,  SET  HEADING,  SET  PATH,  SET  PRINTER 
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UNLOCK 


UNLOCK  releases  record  and  file  locks  so  that  other  users  can  modify  data. 

Syntax 

UNLOCK  [ALL/IN  <  alias  name>  ] 


Usage 

Once  locked,  a  record  or  file  can’t  be  modified  or  updated  by  another  user 
until  the  UNLOCK  command  has  been  executed  to  unlock  the  record  or  file. 

The  UNLOCK  command  unlocks  the  records  or  the  file  in  the  selected  work 
area  that  were  locked  by  the  current  user.  UNLOCK  ALL  releases  all  locks, 
both  file  and  record  locks,  in  all  work  areas.  UNLOCK  IN  <  alias  name> 
unlocks  the  file  lock  or  record  locks  in  the  specified  work  area.  The  ALL  and 
IN  keywords  are  mutually  exclusive. 

This  command  releases  all  record  locks,  if  a  record  lock  was  the  last  lock 
thrown.  It  releases  the  file  lock,  if  a  file  lock  was  the  last  lock  thrown.  Cer¬ 
tain  commands  automatically  lock  the  file  or  record  before  execution.  These 
also  release  the  lock  after  execution,  and  you  usually  do  not  need  to  issue  an 
UNLOCK  unless  the  command  did  not  complete  its  execution. 

If  you  lock  a  file  or  record  that  is  related  to  other  open  files  or  records,  all 
the  files  or  records  in  the  relation  will  be  locked.  Unlocking  the  file  or 
record  automatically  unlocks  all  related  files  or  records. 

Example 

The  following  example  illustrates  using  the  RLOCK()  function  to  lock  a 
record  and  the  UNLOCK  command  to  unlock  it: 

.  USE  Client 
.  ?  RUXKO 
.T. 

.  REPLACE  Lastname  UITH  "Nelsorf 
1  record  replaced 
.  REFUCE  Firstname  WITH  "Jchrf 
1  record  replaced 
.  UUXX 

See  Also 

FLOCK (),  RLOCK()/LOCK(),  SET  RELATION 
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UPDATE 


UPDATE  uses  data  from  another  database  file  to  replace  fields  in  the  current 
database  file.  It  makes  the  changes  by  matching  records  in  the  two  files 
based  on  a  single  key  field. 


Syntax 

UPDATE  ON  <  key  field  >  FROM  <  alias  name> 

REPLACE  <  field  name  1>  WITH  <  expression  1> 

[,<  field  name  2>  WITH  <  expression  2>  ...] 

[RANDOM] 

Usage 

The  database  file  being  UPDATEd  must  be  the  active  file.  The  FROM  database 
file  is  an  open  file  in  another  work  area,  specified  by  its  alias. 

The  key  may  be  only  one  field  in  the  database  file,  not  an  expression  involv¬ 
ing  several  fields  or  a  substring.  The  key  field  must  have  the  same  field  name 
in  both  database  files.  If  the  key  field  in  the  UPDATEd  file  is  not  unique  for 
each  record,  only  the  first  record  that  matches  the  key  field  value  is  updated. 


Options 

Both  files  must  be  either  sorted  or  indexed  on  the  key  field,  unless  RANDOM 
is  used.  RANDOM  requires  the  UPDATEd  database  to  be  indexed  on  the  key 
field;  the  FROM  file,  however,  may  be  in  any  order. 

If  the  REPLACE  expression  involves  a  field  in  the  FROM  database  file  (which 
is  usually  the  case),  the  WITH  field  must  be  identified  as  alias->  field. 
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UPDATE 


Example 

To  update  the  Total_bill  field  of  the  Transact  database  file  with  the  product  of 
the  Qty  and  Item_cost  fields  of  the  Stock  database  file: 


.  LSE  Transact  ORDER  Ordered 
Raster  index:  ORDBUD 

.  REPLACE  ALL  TotaLbill  WITH  0 
TRANSACT:  Record  Nb  1 

12  records  replaced 


.  USE  Stock  ORDER  Ordered  IN  2 
fester  index:  ORD0LID 


.LPOATE  CN  Orderjd  FROM  Stock  REPLACE  TotaU>iLL  UITH  Stodc->Qty  * 
5tock^>I  tensest 

17  records  updated 

.  LIST 

TRANSACT:  Record  lb  1 


■dtt 

CLIBIUD 

CRDERJD 

DATHJRANS 

INDUCED 

TOTALJILL 

1 

A10025 

87-1C6 

02/03/87 

.T. 

650.00 

2 

C000D1 

87-105 

02/10/87 

.T. 

12CD.00 

3 

(HTTP 

87-107 

02/12/87 

.T. 

125D.Q0 

4 

amn 

87-1 CB 

(2/23/87 

.T. 

1250.00 

5 

L0CGD1 

87-1  CP 

03/09/87 

.T. 

165.00 

6 

C000C2 

87-110 

03/09/87 

.T. 

100.00 

7 

irrnn? 

87-111 

03/11/87 

.F. 

1000.00 

8 

looodi 

87-112 

03/20/87 

.T. 

700.00 

9 

A00005 

87-113 

03/24/87 

.T. 

125.00 

10 

B12000 

87-114 

03/30/8 7 

.F. 

45Q.QD 

11 

amn 

87-115 

04/01/87 

.F. 

165.00 

12 

A1CCE5 

87-116 

04/10/87 

.F. 

1000.00 

See  Also 

INDEX,  JOIN,  REPLACE,  SORT 


I 
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USE 


USE  opens  an  existing  database  file,  and  may  open  mdx  and  .ndx  index 
files.  If  the  database  contains  memo  fields,  the  associated  .dbt  file  is  opened 
automatically. 

Syntax 

USE  [<  database  filename >  /?]  [IN  <  work  area  number >  ] 

[[INDEX  <  .ndx  or  mdx  file  list >  ] 

[ORDER  <  .ndx  filename  >  /<  mdx  tag  >  [OF  <  mdx  filename  >  ]] 
[ALIAS  <  alias  name>  ]  [EXCLUSIVE]] 


Defaults 

Unless  IN  <  work  area  number>  is  included,  dBASE  IV  opens  the  database 
file  in  the  currently  selected  work  area. 

USE  ♦♦  closes  the  database  and  any  associated  index  files  in  the  currently 
selected  work  area.  USE  IN  <  work  area  number  >  *■*  closes  the  files  in  the 
named  work  area. 

Unless  you  specify  otherwise,  dBASE  IV  assumes  the  .dbf  extension  for  the 
database  filename  and  the  mdx  or  .ndx  extension  for  the  indexes  specified  in 
an  index  list.  If  you  USE  a  filename  in  the  index  list  without  specifying  a  file 
extension,  dBASE  IV  first  attempts  to  open  an  mdx  file.  If  it  cannot  find  an 
.mdx  file,  dBASE  IV  attempts  to  open  an  .ndx  file. 

If  the  database  filename  isn’t  already  recorded,  USE  <  database  filename  > 
updates  a  catalog  when  one  is  open  and  SET  CATALOG  is  ON. 


USE  ?  displays  a  menu  of  cataloged  .dbf  files  when  a  catalog  is  open,  or  of  all 
.dbf  files  in  the  current  directory  when  a  catalog  is  not  open. 

The  IN  <  work  area  number  >  clause  can  be  used  to  open  files  in  another 
work  area.  The  numeric  expression  may  range  from  1  to  10. 

Indexes  determine  the  order  in  which  records  from  the  database  file  are 
presented.  Index  files  with  an  ndx  extension  are  compatible  with  earlier 
versions  of  dBASE  III  and  dBASE  III  PLUS.  They  contain  a  set  of  pointers  to 
the  database  file  which,  when  the  index  is  invoked,  present  the  records  in 
index  order.  Index  files  with  an  .mdx  extension  may  contain  up  to  47  tags. 
Each  tag  in  the  .mdx  file  is  an  index  and  acts  as  an  ndx  index.  When  you 
open  an  .mdx  file,  you  use  only  one  DOS  file  handle,  but  you  have  access  to 
47  indexes.  When  you  open  an  .ndx  file,  you  use  one  DOS  file  handle,  and 
you  have  access  to  only  one  index. 
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All  open  indexes,  including  mdx  tags,  are  updated  whenever  a  change  is 
made  to  the  associated  database  file.  Up  to  ten  .ndx  files  may  be  opened  for 
each  database  file. 

Each  .ndx  and  .mdx  file  uses  a  DOS  file  handle.  You  are  limited  to  99 
handles  with  the  FILES  setting  in  Config.sys.  Five  file  handles  are  reserved, 
leaving  94  for  dBASE  IV.  If  there  is  sufficient  RAM,  the  maximum  number  of 
files  that  you  can  open  while  running  DOS  is  94. 

After  opening  the  database  file  with  USE,  you  can  open  and  close  all  index 
files  and  tags  with  SET  INDEX.  You  can  also  close  .ndx  files  with  CLOSE 
INDEX  and  DELETE  TAG. 

Options 

The  ORDER  clause  determines  the  controlling  index.  The  index  may  be 
either  an  index  (.ndx)  file  or  a  tag  contained  within  a  multiple  index  (.mdx) 
file;  either  of  these  may  be  specified.  The  controlling  index  contains  the 
index  key  expression  that  the  FIND  and  SEEK  commands  use  for  their 
search.  If  only  one  index  is  open,  that  index  controls  the  index  order  and  the 
ORDER  clause  is  not  needed. 

You  can  indicate  the  .mdx  file  that  contains  the  tag  by  using  the  clause 
OF  <  .mdx  filename  >  .  If  a  tag  is  not  in  the  production  mdx  file,  OF  should 
be  used  to  specify  the  correct  index. 

The  SET  ORDER  command  switches  the  controlling  index  without  closing 
and  re-opening  .ndx  and  .mdx  files. 

ALIAS  allows  you  to  provide  an  alias  name  that  can  be  used  later  to  refer  to 
the  database  file.  If  no  alias  name  is  included,  the  alias  is  the  same  as  the 
database  filename.  You  can  also  use  the  letters  A  through  J,  or  the  numbers 
1  through  10,  to  refer  to  the  ten  work  areas.  When  you  select  a  new  work 
area,  the  database  file  in  that  work  area  becomes  the  active  database  file. 

EXCLUSIVE  opens  the  database  file  with  an  exclusive  file  open  attribute  in  a 
networking  environment.  The  file  is  not  shared,  and  other  users  cannot  USE 
the  database  file  until  you  close  it  with  a  CLEAR  ALL,  CLOSE,  or  USE  com¬ 
mand.  In  a  single-user  environment,  all  files  are  opened  EXCLUSIVE,  and 
dBASE  IV  ignores  this  keyword  in  the  USE  command  line. 
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USE 


Record  Pointer 

When  you  USE  a  database  file  without  any  index  files,  the  record  pointer  is 
positioned  at  the  first  record  in  the  file. 

When  you  USE  a  database  file  with  one  or  more  index  files,  the  record 
pointer  is  positioned  at  the  first  logical  record  of  the  controlling  index.  The 
record  pointer  follows  the  order  of  that  index  until  another  index  is  invoked 
with  SET  ORDER  or  SET  INDEX. 


Special  Case 

Unless  you  provide  an  alias  with  the  ALIAS  keyword,  dBASE  IV  usually 
assigns  the  filename  as  the  default  alias  name.  Some  valid  filenames,  such  as 
X-y,  cannot  be  used  as  alias  names  because  they  contain  characters  that 
dBASE  reserves  for  other  uses.  If  a  filename  contains  characters  that  pro¬ 
hibit  it  from  being  used  as  the  default  alias,  dBASE  assigns  a  letter  alias, 
from  A  to  J,  as  the  default. 


Example 

To  open  the  Client,  Transact,  and  Stock  database  files  in  work  areas  1,  2,  and 
3,  respectively: 

.  CLOSE  ALL 

USE  Client  MEX  CLsjm 
Master  index:  CUS_NW€ 

.  USE  Transact  ORDER  Cl  ientJd  JN  2 
Master  index:  CUENLID 

.  USE  Stock  ORDER  Order_id  IN  3 
tester  index:  ORDEJUD 


See  Also 

CLEAR  ALL,  CLOSE,  COPY  INDEX,  COPY  TAG,  DBF( ),  DELETE  TAG, 
INDEX,  SELECT,  SET  CATALOG,  SET  EXCLUSIVE,  SET  INDEX, 

SET  ORDER,  SET  REPROCESS 
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WAIT  causes  all  dBASE  IV  processing  to  pause  until  any  key  is  pressed. 


Syntax 

WAIT  [  <  prompt  >  ]  [TO  <  memvar>  ] 


Defaults 

If  you  enter  a  or  other  nonprintable  character,  a  null  character  (ASCII 
value  0)  or  graphic  character  is  entered  in  the  memory  variable. 


Usage 

The  prompt  is  a  character  expression.  If  you  do  not  give  a  prompt,  the  mes¬ 
sage  Press  any  key  to  continue  appears. 


Option 

If  you  include  the  TO  <  memvar>  option,  a  character  type  memory  vari¬ 
able  is  created  which  stores  the  keyboard  entry. 


Example 

You  can  use  WAIT  to  temporarily  halt  execution  of  a  dBASE  program.  To  do 
this,  you  could  include  the  following  commands  in  your  program: 

WAIT  'Do  you  wish  to  contirve?  (Y/N)  *  TO  H_ccn 
IF  IFPBWUxn)  *  'N' 

RE71FN 

BDIF 


See  Also 

ON  KEY,  STORE 
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ZAP 


ZAP  removes  all  records  from  the  active  database  file. 

Syntax 

ZAP 

Usage 

ZAP  is  equivalent  to,  but  faster  than,  a  DELETE  ALL  command  followed  by 
PACK. 

If  SET  SAFETY  is  ON,  dBASE  IV  responds  ZAP  <  filename  >  ?  (Y/N). 

Any  open  index  files  in  the  current  work  area  are  automatically  reindexed  to 
reflect  the  empty  database  file. 

dBASE  IV  reclaims  the  space  previously  used  by  the  ZAPped  file,  including 
that  of  any  associated  memo  or  index  files. 

See  Also 

DELETE,  PACK,  SET  SAFETY 
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SET 

Commands 


SET  is  a  full-screen,  menu-driven  command  for  displaying  and  changing  the 
values  of  many  SET  commands. 


Syntax 


SET 


Usage 

At  the  dot  prompt,  type  SET  to  display  the  SET  menu.  The  menu  bar  at  the  top 
of  the  screen  displays  five  selections. 

The  Options  submenu  shows  the  default  settings  for  many  SET  commands.  You 
may  change  the  settings  from  this  menu. 

The  Display  submenu  changes  the  color  and  intensity  display  attributes  associ¬ 
ated  with  text,  headers,  the  status  line  and  fields.  You  can  see  the  actual  screen 
appearance  of  your  selections  in  a  side  window  as  you  make  them.  When  you 
are  satisfied  with  the  appearance  of  your  screen,  press  Esc  or  Ctrl-End.  Either 
mode  of  exit  retains  any  changes  made  to  a  SET  command  for  the  duration  of 
your  current  session  in  dBASE  IV.  When  you  quit  dBASE  IV,  the  values  revert 
to  the  program  defaults. 

The  Keys  submenu  lets  you  program  certain  function  keys  and  key 
combinations. 

The  Disk  submenu  lets  you  change  the  default  disk  drive  and  the  drive  search 
path. 

The  Files  submenu  lets  you  create  alternate,  format,  or  index  file  types. 


See  Also 

For  a  complete  explanation  of  the  SET  menu  screen,  please  refer  to  Using  the 
Menu  System. 

You  can  also  change  the  default  settings  from  the  Config.db  file.  Refer  to 
Chapter  6,  “Customizing  dBASE  IV,”  for  more  information  on  editing  the 
Config.db  file. 
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SET  ALTERNATE 


SET  ALTERNATE  records  all  output  other  than  that  of  full-screen  commands  to 
a  text  file. 

Syntax 

SET  ALTERNATE  on/ OFF 

SET  ALTERNATE  TO  [  <  filename  >  ]  [ADDITIVE] 

Default 

The  default  for  SET  ALTERNATE  is  OFF. 

The  filename  must  include  the  drive  designator  if  the  file  is  not  on  the  default 
drive.  The  file  extension  .txt  is  assumed  unless  otherwise  specified. 

SET  ALTERNATE  TO  ♦♦  closes  an  open  ALTERNATE  file.  CLOSE  ALTERNATE  is 
an  alternative  syntax. 


Usage 

This  command  consists  of  two  parts: 

SET  ALTERNATE  TO  <  filename >  creates  a  text  file  and  opens  the  file.  It 
overwrites  any  file  with  the  sam  ;  name. 

The  ADDITIVE  option  positions  the  cursor  to  the  end  of  the  alternate  file 
before  any  output  is  written  to  it,  so  that  an  existing  file  can  be  appended  to 
without  being  overwritten. 

SET  ALTERNATE  ON  starts  the  recording  of  keyboard  entries  and  screen  dis¬ 
plays  in  the  alternate  file.  Full-screen  operations  such  as  @...SAY,  EDIT, 
BROWSE,  and  APPEND  are  not  recorded. 

You  can  use  SET  ALTERNATE  OFF  to  suspend  writing  to  the  text  file  without 
closing  the  text  file.  You  can  then  start  recording  again  with  SET  ALTERNATE 
ON.  The  text  file  will  not  be  closed  until  you  issue  the  CLOSE  ALTERNATE 
command.  Be  sure  you  issue  the  CLOSE  ALTERNATE  command  before  using 
the  text  file.  The  file  created  by  SET  ALTERNATE  is  a  standard  ASCII  text  file 
which  you  can  edit  with  MODIFY  COMMAND  or  a  word  processor. 

If  you  do  not  want  a  blank  line  at  the  beginning  of  the  alternate  file,  change  the 
?  to  ??.  The  single  ?  always  issues  a  carriage  return  line  feed  before  printing 
text. 
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SET  ALTERNATE 


Examples 

The  commands  below  illustrate  the  SET  ALTERNATE  commands.  To  create  the 
alternate  text  file,  type: 

.  SET ALTEHWE  TO  Textfile 

Commands  executed  after  you  open  an  alternate  file  are  not  recorded  until  you 
SET  ALTERNATE  ON.  Type: 

.SET  ALTEMATE  CN 

All  dBASE  commands  executed  are  stored  in  the  alternate  file  until  you  close 
the  alternate  file  or  suspend  recording  of  commands. 

To  suspend  recording  of  commands,  type: 

.  SET A.TEMH7E  OFF 

To  resume  writing  to  the  text  file,  type: 

.  SET  ALTERNATE  CN 
To  close  the  text  file,  type: 

.  CLOSE  ALTEMTE 

To  demonstrate  the  ADDITIVE  option,  create  a  file  called  Alt_out.txt  using  the 
MODIFY  FILE  command.  Enter  the  following  text: 

Mary  had  a  little  lamb. 

Store  this  file.  Now  execute  the  following  commands: 

.  SETALTEJMTE  TV  Al £_put.  txt  ADDITIVE 
.  SET ALTEFNATE  CN 

.  ?  "uhose  fleece  ms  Uiite  as  arm.0 

The  file  Alt_out.txt  now  contains: 

Mary  had  a  Little  Larrb 
whose  fleece  vas  tirite  as  snow 

See  Also 

CLOSE 
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SET  AUTOSAVE 


The  SET  AUTOSAVE  command  saves  each  record  to  the  disk  after  a  single  I/O 
operation. 

Syntax 

SET  AUTOSAVE  on/OFF 

Default 

The  default  for  SET  AUTOSAVE  is  OFF. 


Usage 

The  SET  AUTOSAVE  command  reduces  chances  of  data  loss  by  saving  records 
to  the  disk  after  each  change  to  a  record.  The  default  is  OFF  to  allow  you  to 
abandon  edits  or  changes  you  are  not  sure  of.  When  SET  AUTOSAVE  is  OFF, 
dBASE  saves  records  to  disk  as  the  record  buffer  is  filled. 

You  can  turn  SET  AUTOSAVE  ON  from  the  dot  prompt,  or  select  ON  from  the 
SET  menu,  or  m  ake  it  a  part  of  your  custom  configuration  in  the  Config.db  file. 


See  Also 

Chapter  6,  “Customizing  dBASE  IV” 
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SET  BELL 


SET  BELL  controls  the  audible  tone  which  alerts  you  to  any  erroneous  or 
invalid  entry.  In  addition  to  turning  it  off  or  on,  you  may  also  set  its  frequency 
and  duration. 

Syntax 

SET  BELL  ON/ off 

SET  BELL  TO  [<  frequency  >  ,<  duration  >  ] 


Defaults 

The  default  for  SET  BELL  is  ON.  The  default  frequency  is  set  to  512  hertz,  and 
the  duration  is  set  to  2  ticks.  Each  tick  is  approximately  0.0549  seconds. 


Usage 

The  available  frequency  range  is  between  18  to  10,001  cycles  per  second.  To  get 

a  lower  pitched  sound,  use  frequencies  between  20  to  550.  To  get  a  higher 

pitched  soundAuse  frequencies  between  550  to  5,500.  The  duration  can  be  from  ^ 

2  to  20  ticks.  The  changes  take  effect  immediately,  and  last  for  the  duration  of 

the  dBASE  IV  session.  To  use  your  own  bell  settings  each  time  you  start 

dBASE  IV  enter  your  BELL  settings  in  the  Config.db  file  as  explained  in 

Chapter  6,  “Customizing  dBASE  IV.” 

To  restore  the  default,  type: 

.  SET  BELL  TO ~ 
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SET  BLOCKSIZE 


SET  BLOCKSIZE  changes  the  default  blocksize  of  memo  fields  and  multiple 
index  (.mdx)  files. 


Syntax 

SET  BLOCKSIZE  TO  <  expN> 


You  may  use  a  numeric  argument  from  1  to  32.  This  command  changes  the 
default  blocksize  of  memo  files  by  multiplying  the  argument  by  512  to  get  the 
actual  blocksize  in  bytes.  The  default  blocksize  is  1,  which  is  the  only  size  that 
is  compatible  with  dBASE  III  PLUS. 

After  the  blocksize  has  been  changed,  memo  fields  that  are  created  with 
CREATE/MODIFY  STRUCTURE  and  COPY  will  have  the  new  blocksize. 

If  an  existing  memo  file  has  an  inefficient  blocksize,  use  the  SET  BLOCKSIZE 
command  to  change  it.  Then  copy  the  database  file  to  a  new  file.  The  new  file 
will  have  the  new  blocksize. 


Tips 

Large  blocks  tend  to  provide  faster  string  manipulation,  but  may  slow  down  I/O 
processing.  Small  blocks  may  provide  slower  string  manipulation,  but  better 
performance. 

If  your  memo  fields  tend  to  be  large,  you  may  increase  the  blocksize  to  7  or  8. 
Too  large  a  blocksize  may  slow  processing  speed. 

You  may  change  the  BLOCKSIZE  parameter  in  the  Config.db  file.  See  Chapter 
6,  “Customizing  dBASE  IV.” 


See  Also 

COPY,  CREATE/MODIFY  STRUCTURE 
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SET  BORDER 


The  SET  BORDER  command  changes  the  default  border  from  a  single  line  box 
to  several  user-defined  border  characters. 


Syntax 

SET  BORDER  TO  [SINGLE/ DOUBLE/ PANEL/ NONE/ 

<  border  definition  string >  ] 

The  border  definition  string  may  be  defined  as: 

[<  1>  ]  [,[<  2 >  ]  [,[<  3  >  ]  [,[<  4 >  ]  [,[<  5  >  ] 

[,[<  6  >  ]  [,[<  7  >  ]  [,[<  8  >  ]]]]]]]] 

where  each  number  1  through  8  is  a  decimal  value  for  any  IBM  ASCII  charac¬ 
ter.  The  required  order  for  specifying  the  sides  and  the  corners  using  1  through 
8  is  illustrated  below  in  Figure  3-1. 


3  4 


7 - 2 - ls 

Figure  3-1  Order  of  bordcler  characters 


Default 

The  default  border  is  a  single  line  box. 


Usage 


->y 


You  can  change  the  default  border  with  the  SET  BORDER  command  to  a  dou¬ 
ble  line  box,  to  an  inverse  video  panel,  or  any  other  ASCII  character,  or  to  no 
border  at  all. 

SET  BORDER  TO  DOUBLE  changes  the  border  to  a  double  line  box. 

SET  BORDER  TO  ♦♦  restores  the  default  single  line  box. 

SET  BORDER  TO  PANEL  gives  an  inverse  video  box  as  if  ASCII  219  were 
entered. 


The  border  setting  also  affects  @...SAY,  and  @...TO  commands.  Lines  drawn 
with  the  @  commands  use  the  SET  BORDER  default. 
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SET  BORDER 


Examples 

To  set  a  border  that  is  double  lines  on  top  and  bottom,  single  lines  at  the  sides, 
and  single  line  corners,  enter  the  command: 

.SET BORDER  TD  DCLBLE 
.  SET  BORDER  TO  ,,  179, 179^13, 1&^12, 190 

First  you  set  the  border  to  double  lines.  Then  you  define  a  new  border,  using 
the  ASCII  values  for  the  line-drawing  characters  of  the  IBM  extended  character 
set.  The  two  commas  retain  double  lines  for  the  top  and  bottom  borders.  The 
value  179  sets  the  left  and  the  right  side  to  a  single  line.  The  corner  characters 
combine  horizontal  double  lines  and  vertical  single  lines.  Thus,  they  match  the 
top  and  bottom  borders.  The  two  SET  BORDER  TO  commands  can  be  com¬ 
bined  into  one  command  as  follows: 

.  SET  BORDER  TO  205^05, 179, 179^13, 1*^12, 190 

To  set  a  border  that  is  an  inverse  video  bar,  enter  the  command: 

.SET BORDER  TO  FWEL 

See  Also 

@...SAY,  @...TO 
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SET  CARRY 


SET  CARRY  updates  all  fields,  or  only  specified  fields,  depending  on  the  syntax 
you  use. 

Syntax 

SET  CARRY  on /OFF 

This  command  carries  forward  all  changes  made  in  BROWSE  or  EDIT. 

SET  CARRY  TO  [<  field  list  >  ]  [ADDITIVE] 

This  command  updates  the  specified  fields  only  when  you  change  them  using 
APPEND,  BROWSE,  or  INSERT. 

Default 

The  default  for  SET  CARRY  is  OFF. 

The  command  does  not  affect  INSERT  BLANK  or  APPEND  BLANK;  a  blank 
record  is  still  added. 


Usage 

When  SET  CARRY  is  ON,  all  fields  are  updated. 

If  you  use  SET  CARRY  TO  <  field  list  only  the  specified  fields  are  updated.  v 

This  command  ignores  SET  FIELDS,  allowing  you  to  carry  fields  forward  in 
BROWSE  window. 

If  you  use  the  ADDITIVE  option,  the  fields  in  the  fields  list  are  added  to  the  list 
of  previous  fields  specified  with  SET  CARRY. 

SET  CARRY  with  no  fields  list  returns  to  the  default  condition  where  all  the 
fields  are  updated. 

If  SET  CARRY  is  OFF,  no  fields  are  updated.  Issuing  a  SET  CARRY  TO  auto¬ 
matically  turns  SET  CARRY  to  ON  so  that  the  fields  list  can  be  updated. 

See  Also 

@,  APPEND,  INSERT,  READ,  SET  FORMAT 
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SET  CATALOG 


The  SET  CATALOG  command  is  used  to  create  or  open  a  catalog  file.  When  a 
catalog  is  open  and  SET  CATALOG  is  ON,  new  files  which  you  use  or  create  are 
added  to  the  catalog. 


Syntax 

SET  CATALOG  on/ OFF 

SET  CATALOG  TO  [  <  filename  >  ]/? 


Default 

The  default  for  SET  CATALOG  is  OFF,  and  no  catalogs  are  selected.  However, 
selecting  a  catalog  with  SET  CATALOG  TO  automatically  SETs  CATALOG  ON. 


Usage 

Use  SET  CATALOG  TO  <  filename  >  to  open  an  existing  catalog  or,  if  one 
doesn’t  exist,  to  create  a  new  catalog.  Catalog  filenames  are  limited  to  eight 
characters.  dBASE  IV  always  assigns  the  extension  (.cat)  to  catalog  filenames. 

If  you  SET  TITLE  ON  when  you  create  a  new  catalog,  dBASE  IV  asks  you  to 
enter  a  one-line  description  of  the  catalog  file.  The  description  you  enter  for 
each  catalog  entry  is  displayed  liter  when  you  use  the  SET  CATALOGTO  ?  com¬ 
mand  to  select  and  highlight  a  catalog  name. 

A  master  catalog  file,  Catalog. cat,  is  created  the  first  time  you  create  a  catalog. 
dBASE  always  checks  to  see  if  this  main  catalog  exists,  and  creates  it  if  it  does 
not  exist.  The  master  catalog  is  stored  in  the  current  directory  and  keeps  track 
of  other  catalogs.  You  can  create  different  master  catalogs  in  other  drives  or 
directories. 

The  master  catalog  allows  you  to  use  the  SET  CATALOG  TO  ?  command.  It 
stores  catalog  filenames  along  with  the  catalog  title  descriptions. 

Catalogs  are  database  files  which  have  a  predefined  file  structure.  When  you 
create  or  select  a  catalog  file,  it  is  automatically  opened  in  work  area  10.  When 
a  catalog  is  open,  work  area  10  is  reserved  for  the  system  to  update  the  catalog 
file,  so  you  cannot  select  and  use  that  work  area  for  another  database  file. 

When  you  open  or  create  a  new  catalog,  SET  CATALOG  is  automatically  set  ON. 
From  then  on,  all  database  files  (and  associated  files  such  as  index,  query, 
report,  and  label  files)  you  use,  or  new  files  you  create,  are  added  to  the  cata¬ 
log.  With  SET  CATALOG  ON,  the  open  catalog  records  entries  for  files  associ¬ 
ated  with  open  database  files.  The  catalog  is  updated  automatically  by  certain 
commands  such  as  CREATE,  INDEX,  and  CREATE/ MODIFY  REPORT. 
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Whenever  you  open  a  catalog,  dBASE  checks  the  catalog  contents  against  the 
disk.  If  you've  previously  deleted  any  files  with  SET  CATALOG  OFF,  dBASE 
updates  the  catalog  by  deleting  the  files  that  are  in  the  catalog  but  have  been 
deleted  from  the  disk. 

If  you  decide  you  want  to  close  a  catalog,  use  the  command,  SET  CATALOG  TO 
with  no  argument.  If  you  just  want  to  stop  adding  files  to  an  open  catalog,  you 
can  SET  CATALOG  OFF.  Then,  when  you  want  to  resume  adding  files  to  the  cat¬ 
alog,  SET  CATALOG  ON  again. 

SET  CATALOG  OFF,  unlike  turning  off  the  catalog  with  SET  CATALOG  TO  with 
no  argument,  keeps  the  catalog  open  and  allows  you  to  use  the  query  clause  (?) 
with  other  dBASE  commands.  For  example,  with  SET  CATALOG  OFF,  you  can 
type  MODIFY  REPORT  ?,  and  dBASE  IV  activates  a  menu  list  of  .frm  files  in 
the  open  catalog.  Because  the  files  in  the  catalog  are  linked  with  the  database 
file  they  were  created  or  used  with,  only  the  files  relevant  to  the  active  database 
file  are  listed. 


NOTE 

If  SET  CATALOG  is  OFF  when  a  database  Gle  is  used  and  is  later  set  OH, 
Gles  you  use  with  the  open  database  file  (for  example,  an  index  file)  are 
not  added  to  the  catalog.  dBASE  IV  displays  the  message  File  not  cata¬ 
loged,  since  SET  CATALOG  was  OFF  when  the  active  database  Gle  was 
USEd. 


Catalog  Structure 

All  catalogs  have  the  same  file  structure.  The  structure  is  shown  in  Table  3-1. 


Table^ 3-1  Catalog  structure  l_ 


Field 

Reid  Name 

Typa 

Width  Dec 

1 

Path 

Character 

70 

2 

File_name 

Character 

12 

3 

Alias 

Character 

8 

4 

Type 

Character 

3 

5 

Title 

Character 

80 

6 

Code 

Numeric 

3 

7 

Tag 

Character 

4 

••  Total  •• 

181 
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With  the  exception  of  the  Title  and  Tag  fields,  dBASE  IV  automatically  fills  in 
the  field  contents  whenever  a  new  file  is  entered  in  the  catalog.  There  are 
instances  in  which  a  field  is  intentionally  left  blank.  For  example,  the  Alias  field 
is  used  to  define  database  (  dbf)  files,  and  left  blank  with  other  types  of  files  that 
do  not  have  ^Qias  names. 

Path 

Enter  the  path  statement  when  the  catalog  is  not  on  the  default  drive  and  path. 
dBASE  IV  uses  the  full  file  specification  along  with  the  filename  in  a  file 
search.  The  path  statement  is  stored,  exactly  as  it  is  entered,  with  the  filename. 

File_name 

This  is  the  name  of  the  file,  including  its  extension. 

Alias 

If  you  do  not  assign  an  alias  name,  dBASE  IV  uses  the  database  filename  as  the 
alias  name.  This  field  is  left  blank  for  all  other  file  types. 

Typo 

This  field  contains  the  default  file  extension  that  identifies  the  type  of  file.  Even 
if  you  specified  a  different  extension  when  creating  the  file,  the  default  exten¬ 
sion  is  entered  in  the  Type  fielc .  However,  the  extension  that  you  specified  is 
included  in  the  File_name  field. 

Title 

This  is  an  optional  field.  If  SET  TITLE  is  ON,  dBASE  IV  prompts  you  to  add  a 
description  when  you  create  the  catalog.  You  have  up  to  80  spaces  to  describe 
the  contents  of  the  new  catalog.  If  you  want  to  change  this  description,  and  the 
catalog  is  not  in  USE,  type: 

.  USE  <cataLog  nam.cat> 

.  EDIT 

If  the  catalog  is  in  USE: 

.  SELECT  10 
.  EDIT 
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Code 


When  you  have  a  catalog  open,  Code  is  the  number  dBASE  IV  assigns  to  each 
database  file  put  into  USE. 

Associated  index  (.ndx),  multiple  index  (.mdx),  format  (.fmt),  label  (  lbl),  query 
(.qry),  report  form  (.frm),  screen  (.scr),  and  view  (,vue)  files  are  also  assigned 
the  same  number. 

Tag 

This  field  is  not  used. 


Adding  Entries 


When  SET  CATALOG  is  ON,  a  new  entry  is  added  automatically  to  the  active 
catalog  when  you  use  any  of  the  following  commands: 


COPY  STRUCTURE 

COPY  STRUCTURE  EXTENDED 

COPY  TO 

CREATE 

CREATE  FROM 

CREATE/ MODIFY  LABEL 

CREATE/  MODIFY  QUERY 

CREATE/  MODIFY  REPORT 

CRE ATE/  MODI FY  SCREEN 

CREATE/ MODIFY  VIEW 


IMPORT  FROM 

INDEX 

JOIN 

SET  FILTER  TO  FILE 

SET  FORMAT 

SET  VIEW 

SORT 

TOTAL 

USE 


If  the  filename  already  exists  in  the  catalog,  you  are  prompted  for  a  file  title 
(if  SET  TITLE  is  ON).  Each  of  these  commands  also  allows  you  to  select  files 
using  the  ?  query  from  the  currently  open  catalog,  regardless  of  whether  SET 
CATALOG  is  ON  or  OFF. 


NOTE 

Use  the  SET  TITLE  OFF command  to  suppress  the  file  title  prompt,  if  you 
do  not  want  to  enter  file  titles,  lb  prevent  the  catalog  from  being 
updated,  use  the  SET  CATALOG  OFF  command. 


See  Also 

SET  TITLE 
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SET  CENTURY 


SET  CENTURY  allows  the  input  and  display  of  century  prefixes  in  the  year  por¬ 
tion  of  dates. 


Syntax 

SET  CENTURY  on/OFF 


Default 

The  default  for  SET  CENTURY  is  OFF.  Digits  representing  the  century  are  not 
displayed  and  cannot  be  entered. 

The  default  date  entry  and  display  allows  only  two  digits  for  the  year  entry  (cur¬ 
rent  twentieth  century  only).  However,  if  a  date  calculation  results  in  a  non¬ 
twentieth  century  date,  this  value  can  be  placed  into  a  date  field,  and  it  will 
retain  the  correct  century.  If  the  field  is  edited  with  a  full-screen  editing  com¬ 
mand  and  SET  CENTURY  is  OFF,  the  year  is  changed  to  a  twentieth-century 
date. 

Although  the  four-digit  year  displayed  with  SET  CENTURY  ON  makes  the  date 
display  ten  characters,  the  database  field  size  is  always  eight  bytes.  This  is 
because  dates  are  stored  internally  as  numbers.  Also,  the  format  in  which  a 
date  is  displayed  does  not  affect  its  internal  storage. 


With  SET  CENTURY  ON,  the  date  display  contains  a  four-digit  year.  When  SET 
CENTURY  is  OFF,  the  year  is  displayed  in  two  digits,  with  the  twentieth  century 
assumed. 

SET  CENTURY  affects  all  full-screen  editing  commands  and  date  displays. 

When  SET  CENTURY  is  OFF,  you  can  input  only  twentieth  century  dates. 


Example 

.  ?  DATEO 
02/14/88 
.  SET  CENlURf  CN 
.  ?  DATEO 
02/14/1988 
.  SET  CB/llFf  OFF 


3-14 


See  Also 

CTODQ,  DATE(),  DTOC(),  YEAR() 


SET  COMMANDS 


PAGE:  15  SESS:  12  Thu  Har  24  17:  14:  11  1988 

2/a  1  I  job*/CLSjnanhat/GRPjnanhat/J0Bjnanlangref/DIV_lrchap3 


SET  CLOCK 


SET  CLOCK  controls  the  display  and  screen  position  of  the  system  clock. 


Syntax 

SET  CLOCK  on/ OFF 

SET  CLOCK  TO  [  <  row  >  ,  <  colum  n  >  ] 

Defaults 

The  default  setting  for  the  clock  is  OFF.  When  the  clock  is  turned  on,  the 
default  setting  is  at  row  Jt,  column  68. 

4 


Usage 

Use  the  SET  CLOCK  command  to  display  the  system  clock  and  to  determine  its 
location.  SET  CLOCK  TO  turns  the  clock  on  and  positions  its  display. 

The  clock  display  is  not  suppressed  with  full-screen  menu  commands,  regard¬ 
less  of  its  setting. 
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SET  COLOR  allows  the  selection  of  colors  and  display  attributes  for  use  on 
color  and  monochrome  monitors. 


Syntax 


SET  COLOR  ON/ OFF 


SET  COLOR  TO  [[<  standard  >  ]  [,<  enhanced  >  ]  [,<  perimeter  >  ] 
[,  <  background  >  ]] 


where  standard  and  enhanced  settings  specify  foreground  and  background  col¬ 
ors  separated  by  /.  ^ 

SET  COLOR  OF  NORMAL/ MESSA3ES/TITLES/ BOXES/ HIGHLIGHT/ ALERT^J 
~  FIELDS  TO  [  <  attribute  >  ] 

allows  setting  or  changing  the  color  attributes  of  individual  display  areas. 


Defaults 

SET  COLOR  ON/OFF  switches  between  color  and  monochrome  monitors  on 
systems  equipped  with  both.  The  default  is  whatever  the  system  is  using  when 
you  start  dBASE  IV. 

SET  COLOR  TO  ♦♦  resets  the  screen  to  dBASE  IV  default  colors  which  are 
coded  into  the  program.  This  command  does  not  reset  to  the  color  definitions 
you  may  have  included  in  the  Config.db  file. 

k)ort  TO  3rd  it 

A 

standard:  white  on  black 
background:  black  on  white 
MONO 
standard:  dim 

background:  dim,  dim  reverse 

Each  time  you  start  dBASE  IV,  any  color  settings  you  have  placed  into  the 
Config.db  file  will  override  the  program  defaults. 


The  default  settings  are: 

{jStill  waiting  on  3/22/88  for  Marketing  Decision}} 
COLOR 
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Usage 

Use  the  SET  COLOR  TO  command  to  select  the  colors  to  display  text,  back¬ 
ground,  and  highlighted  areas  on  your  screen. 

On  an  enhanced  graphics  adapter  (EGA or  compatible  color  graphics  adapters), 
when  you  select  the  colors  from  the  SET  command  full-screen  menu,  you  can 
see  the  selections  displayed  in  a  small  side  menu.  Other  screen  attributes  such 
as  intensity,  blanking,  or  blinking  are  also  displayed  on  the  the  small  side  menu 
when  you  select  them. 

Your  selections  take  effect  as  soon  as  the  screen  is  refreshed;  for  instance, 
when  you  change  to  another  menu  or  to  a  43-line  display. 

The  settings  revert  to  the  default  colors  when  you  quit  dBASE  IV.  To  store  a 
color  setup  in  the  Config.db  file  as  your  default  setting,  refer  to  Chapter  6, 
“Customizing  dBASE  IV.” 

You  can  change  the  color  settings  by  specifying  letter  codes  for  each  of  the 
types  of  displayed  text:  standard,  enhanced,  border,  and  background.  The  let¬ 
ters  used  to  select  colors  are  as  follows: 


Table  3-2  Color  table 


Color 

Letter  Code 

Color 

Letter  Code 

Black 

N  or  blank 

Red 

R 

Blue 

B 

Magenta 

RB 

Green 

G 

Brown 

GR 

Cyan 

BG 

Yellow 

GR  + 

Blank 

X 

White 

W 

Gray 

N  + 

To  specify  blinking,  place  an  asterisk  (*)  following  the  color  letter.  To  specify 
blanking,  place  an  X  for  the  color  letter.  To  specify  high  intensity,  place  a  plus 
(+  )  next  to  the  color  letter  (except  for  brown,  yellow,  and  gray  colors).  The 
hardware  of  the  EGA  card  does  not  allow  you  to  set  high  intensity  colors  as  the 
background.  If  you  do,  the  setting  will  be  the  normal  intensity  version  of  the 
same  color. 

For  display  adapters  that  allow  you  to  set  different  colors  for  standard  and 
enhanced  text  areas,  set  the  standard  and  enhanced  colors  as  foreground/back¬ 
ground  and  enhanced  foreground/background  pairs.  For  example,  SET  COLOR 
TO  G/B,  GR+  /N  sets  standard  colors  to  green  on  a  blue  background,  and 
enhanced  colors  to  yellow  on  a  black  background. 
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For  display  adapters  that  require  the  same  background  for  standard  and 
enhanced  areas,  specify  the  foreground  colors  individually,  and  then  set  the 
background  color.  For  example,  SET  COLOR  TO  B,  G,  R  displays  standard  text 
as  blue  over  red  standard  display  areas,  and  enhanced  (highlighted)  text  as 
green  on  red  with  a  green  on  red  border. 

You  can  also  selectively  change  one  of  the  color  settings.  For  example,  when 
specifying  foreground/background  pairs,  you  can  omit  the  foreground  or  back¬ 
ground  color.  When  you  do  not  specify  a  color,  either  before  or  after  the  slash 
in  the  foreground/background  pair,  the  color  black  is  selected. 

If  you  do  not  want  characters  in  a  specific  area  to  appear  on  your  screen  (for 
instance,  for  a  password  entry),  specify  Blank  (X)  for  either  a  foreground  or 
background  color  in  those  areas. 


For  a  monochrome  monitor,  you  can  specify  the  letters  U  for  underline  and  I 
for  inverse  video  instead  of  using  colors  to  provide  emphasis  for  standard  and 
enhanced  foreground  text.  If  you  do  specify  colors,  or  the  letters  U  or  I,  make 
sure  they  work  properly  for  the  particular  display  adapter  and  application  you 
are  running. 

The  syntax  SET  COLOR  ...OF.. .TO  controls  predefined  screen  area  groupings  so 
that  you  can  change  color  attributes  of  individual  screen  areas  independent  of 
one  another.  £t^r\dard  cSkvd  enhanced  s crests  area  ^,-oopje  are  5 umrnon 


Table  3-J^  Color  attribute  groups  of  screen  areas 


Attribute 

Group  Names 

StandarcUAII^* 

^Controlled7 Areas  of  Screen 

NORMAL 

Uncontrolled  @...SAY  output 

Unselected  fields  in  BROWSE 

Layout  editor  design  surface  (dim) 

Unselected  text  on  design  surface 

Unselected  uncolored  display  only  field  templates 

Static  memo,  window  borders 

Conditions  in  QBE  file  skeleton 

Conditions  in  QBE  condition  box 

Calculated  field  expressions 

Unselected,  uncolored  box  borders  in  Layout  editor 

Uncolored  box  borders  drawn  with  @...TO  command 
User-entered  text  in  the  Applications  Generator 

3 

A 
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Table  3-tf  Color  attribute  groups  of  screen  areas  {continued) 


Attribute 

Group  Names 

Standard^jU^ 

(Controlled  Areas  of  Screen 

MESSAGES 

Message  line  bright  messages 

Navigation  line  messages 

Available,  unselected  menu  and  list  choices  (bright) 
Unavailable  menu  and  list  choices  (dim) 

Error  box  interiors 

Help  box  interiors 

Bolded  Help  box  text  (bright) 

Prompt  box  interiors 

Unselected  prompt  box  buttons  (bright) 

Unselected  error  box  buttons  (bright) 

Unselected  Help  box  buttons  (bright) 

flTLES 

List  headings 

Help  box  headings 

Control  Center  banner 

Control  Center  catalog  name  heading  and  filename 
Control  Center  filename  and  file  description  headings 
BROWSE  field  name  headings 

BROWSE  table  grids  (dim) 

Database  design  column  labels 

Database  design  field  numbers 

Unselected  report  design  band  lines 

QBE  file  skeleton  field  names  and  filename 

QBE  view  skeleton  field  names  and  view  name 

QBE  view  skeleton  grid  (dim) 

QBE  file  skeleton  grids  (dim) 

QBE  calculated  fields  skeleton  grids  (dim) 

QBE  condition  box  border  (dim) 

QBE  condition  box  heading 

Ruler  line 

Text  styles  defined  with  the  Style  menu  (bright) 
End-of-Report  line  in  report  design 

Text  that  is  underlined  in  Help  screens  (bright) 

Static  text  in  Applications  Generator  forms 

Underlined  Help  box  text  (bright) 

Database  design  grid 

-i-  /  fs4  *v £  \*s0/f 
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Table  3-/  Color  attribute  groups  of  screen  areas  (> continued! 


Attribute 
Group  Names 

HIGHLIGHT 


Enhanced*/^  jl^y 
(ControllegXfreas  of  Screen 

Highlighted  menu  and  list  choices 
Highlighted  prompt  box  buttons 
Selected  static  text  on  design  surface 
Selected  Held  on  design  surface 
Selected  box 

Control  Center  filename  and  file  description 

Flying  cursor  in  ruler  lin^—. - 

Report  design  selected  band  lines  v 

Information  box  borders 
Information  box  interiors 
Current  Held  in  the  Applications  Generator 
Static  text  under  the  cursor  on  design  surface 
Box  under  the  cursor  on  design  surface 
—Box  under  the  cuisui  oirduign  surface - 

Field  under  the  cursor  on  design  surface 


'r 


us 


BOXES  Menu  borders 

List  borders 
Prompt  box  borders 
Label  design  layout  box  border 

Unselected  /pplications  Generator  object"  border" 

ALERT  Clock 

Error  box  borders 
Help  box  borders 
Status  line 

Selected  button  in  error  box 
Selected  button  in  Help  box 


FIELDS  Prompt  box  data  entry  areas 

Selected  field  in  BROWSE 
Editable  fields  in  @...GET 
Database  design  in  selected  field 
Editable  field  design  surface  field  templates 
Unselected  fields  in  the  Applications  Generator 
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Special  Case 

The  older  Compaq  portable  computers  with  built-in  monochrome  monitors 
function  as  though  they  have  color  monitors.  Thus,  monochrome  attribute’sTU 
and  I  do  not  generate  underlining  and  inverse  video.  The  color  settings  are^" 
translated  to  shades  of  black  and  green.  On  these  monitors,  NORMAL  bright  is 
not  the  same  color  as  MESSAGES  bright. 

Examples 

lb  set  a  color  display  with  a  standard  display  that  uses  enhanced  intensity  white 
letters  on  a  blue  background,  and  an  enhanced  display  that  uses  yellow  letters 
on  a  black  background,  at  the  dot  prompt,  type: 

.  SET  COLOR  TO  W-/BJ3&/N 

Because  it  is  easier  to  see  menu  selections  against  a  different  background,  it  is 
recommended  that  you  use  a  different  background  color  on  the  enhanced  dis- 
play. 

The  status  line  is  part  of  the  ALERT  grouping.  You  can  set  the  status  line  to  a 
different  color  pair,  for  example  enhanced  white  on  red.  Type: 

.SET  COLOR  OF  ALERT  TO  Vtft 

and  the  status  line  changes  to  intense  white  on  red  while  the  screen  remains 
intense  white  on  blue  for  regular  text,  and  yellow  on  black  for  Helds  and  menu 
bars.  When  displayed,  the  clock  has  the  same  colors  as  the  status  line. 


See  Also 

SET,  SET  DISPLAY 
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SET  CONFIRM  determines  cursor  movement  at  the  end  of  an  entry  field 


Syntax 

SET  CONFIRM  on/ OFF 

Default 

The  default  for  SET  CONFIRM  is  OFF. 

Usage 

SET  CONFIRM  OFF  causes  the  cursor  to  advance  from  one  entry  field  to  the 
next  when  the  first  entry  field  is  filled. 

SET  CONFIRM  ON  causes  the  cursor  to  remain  at  the  last  space  in  an  entry 
field  until  is  pressed. 
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SET  CONSOLE 


SET  CONSOLE  turns  the  screen  display  on  and  off  from  within  a  program 


Syntax 

SET  CONSOLE  ON/o£f 

Default 

The  default  for  SET  CONSOLE  is  ON. 


SET  CONSOLE  works  only  within  a  program  and  suppresses  output  to  the 
screen.  Use  SET  CONSOLE  OFF  to  prevent  the  display  of  reports  and  programs 
routed  to  the  printer. 

You  cannot  SET  CONSOLE  OFF  from  the  dot  prompt. 

When  the  console  is  off,  keyboard  input  is  allowed.  You  can  type  in  input 
requested  by  commands  such  as  WAIT  and  ACCEPT;  however,  the  screen 
remains  blank.  You  can  see  neither  the  prompts  from  these  commands  nor 
what  you  are  typing. 

@...SAY...GETs  override  the  CONSOLE  setting  and  are  visible  regardless  of  the 
SET  CONSOLE  status. 

SET  CONSOLE  OFF  does  not  suppress  error  messages. 
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SET  CURRENCY 


The  SET  CURRENCY  command  changes  the  symbol  used  for  currency. 

Syntax 

SET  CURRENCY  TO  [  <  expC>  ] 

Usage 

This  command  changes  the  symbol  associated  with  the  currency  unit  used  in 
monetary  data  and  calculations.  dBASE  IV  allows  a  maximum  of  nine  charac¬ 
ters  to  be  used  for  this  symbol. 

Usually,  changing  the  currency  symbol  also  involves  changing  the  decimal 
point  to  a  comma,  and  changing  the  numeric  separator  to  a  period.  When  used 
with  PICTURE  clauses,  the  SET  CURRENCY  command  changes  the  currency 
symbol  that  is  displayed. 


Examples 

a  SET  CURRENCY  TO  'ON 
.STORE  125,456.78  TO  Muter 
.3  10/3  SAY  MJEER  PICTURE  03T 


results  in: 

DM1 23/456.78 


An  example  of  using  the  $  PICTURE  template  follows.  Notice  that  you  do  not 
enter  the  separator  character  when  storing  a  number. 


.SET  POINT  TO  V 

.SET SEPARATOR  T0'.u 

.SET  CLRRBCr  TO  'ON 

.STORE  125456.78  TO  Huber 

.3  10/3  SAT  Muter  PICTURE  '$SS/S$^S$.9? 


results  in: 

D00M123.456,78 


To  prevent  the  letter  D  from  repeating,  put  a  space  as  the  first  character  of  the 
currency  symbol  and  repeat  the  command.  The  result  is: 

DM123.456,78 
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SET  CURRENCY 
LEFT/RIGHT 


SET  CURRENCY  LEFT/RIGHT  changes  the  position  of  the  currency  symbol 
from  the  left  of  the  currency  amount  to  the  right  of  the  currency  amount. 

Syntax 

SET  CURRENCY  LEFT/ right 

Default 

The  default  for  SET  CURRENCY  is  LEFT. 


The  default  is  for  the  currency  symbol  to  be  on  the  left  of  the  currency  amount. 
This  command  positions  the  symbol  to  the  right  for  currencies  that  use  the 
right  convention,  such  as  the  French  franc.  To  change  the  default,  modify  the 
Config.db  file  as  described  in  Chapter  6,  “Customizing  dBASE  IV.” 


Examples 

To  change  the  currency  display  to  the  right  of  the  amount  for  the  French  franc, 
type: 


.SET  CURRENCY  RIGHT 
.SET  CLPFENCf  TO  'FJT 
.SET  POINT  TO  V 
.SET  SEPARATOR  TO'.' 

.STORE  500D35  TO  AMJLNT 
.3  10/1  SAY  AKLNT  PICTURE  '3T 
5GQ0y25FR 
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SET  DATE 


SET  DATE  determines  the  format  for  date  displays. 


Syntax 

SET  DATE  AMERICAN/ansi/british/french/german/italian/japan/ 
usa/mdy/dmy/ymd 


Default 

The  default  setting  for  DATE  is  AMERICAN. 


3-26 


Usage 

This  command  allows  flexibility  in  date  input  and  output.  You  can  quickly 
change  the  date  output  format  with  this  command. 

You  can  also  change  the  default  date  format  by  placing  this  option  in  the 
Config.db  Hie.  See  Chapter  6  for  customizing  the  Config.db  file. 

The  date  formats  available  to  the  SET  DATE  TO  command  are: 


AMERICAN 

mm/dd/yy 

ANSI 

yy.m  m  .dd 

BRITISH/ FRENCH 

dd/mm/yy 

GERMAN 

dd.mm.yy 

ITALIAN 

dd-mm-yy 

JAPAN 

yy/mm/dd 

USA 

m  m  -dd-yy 

MDY 

mm/dd/yy 

DMY 

dd/mm/yy 

YMD 

yy/mm/dd 
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SET  DEBUG 


SET  DEBUG  is  a  tool  for  locating  errors  in  a  program.  It  determines  whether 
output  from  SET  ECHO  is  sent  to  the  screen  or  printer. 


Syntax 

SET  DEBUG  on/OFF 

Default 

The  default  for  SET  DEBUG  is  OFF. 

Usage 

When  SET  DEBUG  is  ON,  the  output  of  SET  ECHO  is  routed  to  the  printer.  This 
prevents  interference  between  the  program's  screen  operations  and  the  screen 
displays  that  are  normally  generated  by  the  debugging  process. 

With  both  SET  DEBUG  ON  and  SET  ECHO  ON,  outputs  for  the  SET  TALK  (for 
example,  the  number  of  records  indexed),  LIST/and  DISPLAY  commands,  and 
error  messages  are  aot sent  to  the  printer  unless  SET  PRINTER  is  ON. 

See  Also 

DEBUG,  SET  ECHO,  SET  TALK 
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SET  DECIMALS 


SET  DECIMALS  determines  the  number  of  decimal  places  that  dBASE  IV  dis¬ 
plays  for  the  results  of  numeric  functions  and  calculations. 


Syntax 

SET  DECIMALS  TO  <  expN  > 

where  <  expN>  is  a  numeric  expression  between  0  and  15. 


Default 

The  default  is  two  decimal  places. 


Usage 

SET  DECIMALS  applies  to  division,  multiplication,  and  all  mathematical,  trigo¬ 
nometric,  and  financial  calculations. 

The  maximum  number  of  decimals  is  15.  This  means  that  a  maximum  of  19 
numbers  including  the  decimal  point  and  two  numbers  to  the  left  of  the  deci¬ 
mal  point  can  be  displayed. 


Example 

Compare  the  results  of  several  calculations  using  different  decimal  place 
settings. 


.  ?3/4 
0.75 

.  ?  sortm^d 

2.09 

.  SET  DECIMALS  TO  4 
.  ?3/4 
0.7500 

.  ?  SGRTC4.3?) 
2.0505  ' 
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SET  DEFAULT 


SET  DEFAULT  allows  the  user  to  select  the  drive  where  all  operations  take 
place  and  all  files  are  stored. 

Syntax 

SET  DEFAULT  TO  <  drive  > 

Default 

The  default  drive  is  the  drive  from  which  you  started  dBASE  IV. 

When  you  change  drives  with  SET  DEFAULT  TO,  the  default  directory  is  the 
directory  last  specified  on  that  drive.  For  example,  if  you  go  to  drive  A  from 
drive  C  subdirectory  \DATA,  when  you  return  to  drive  C  you  will  be  in  \DAFA 

SET  DEFAULT  does  not  check  whether  or  not  the  named  drive  exists  and  does 
not  change  the  drive  to  which  you  return  when  you  quit  dBASE  IV. 

Refer  to  Chapter  6,  “Customizing  dBASE  IV,”  to  find  out  how  to  set  the  default 
drive  in  the  Config.db  file. 

Example 

If  the  Customer  database  file  is  located  on  disk  drive  Abut  dBASE  IV  was 
started  from  drive  C,  typing  the  following  command: 

.  USE  Qjstamr 

results  in  the  message  File  Castomer.dbf  does  not  exist.  To  change  the  default 
drive  and  open  the  database  file,  type: 

.  SET  DEFAULT  TO  A 
.  USE  CLstcmr 

See  Also 

SET  PATH 
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SET  DELETED 


SET  DELETED  determines  whether  records  that  are  marked  for  deletion  are 
included  or  ignored  by  other  dBASE  IV  commands. 

Syntax 

SET  DELETED  on/OFF 

Default 

The  default  for  SET  DELETED  is  OFF. 


Usage 

INDEX  and  REINDEX  always  include  all  records  regardless  of  the  status  of 
SET  DELETED. 

With  SET  DELETED  ON,  most  commands  do  not  consider  deleted  records  part 
of  the  file.  For  example,  dBASE  IV  will  not  LOCATE  or  LIST  deleted  records. 
However,  if  you  DISPLAY  a  scope  of  records  or  GOTO  a  specific  record,  then 
you  will  see  records  marked  for  deletion. 

If  SET  DELETED  is  ON,  RECALL  ALL  does  not  recall  any  records,  because  the 
deleted  records  are  ignored. 

See  Also 

DELETED 
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SET  DELIMITERS 


SET  DELIMITERS  determines  how  field  widths  are  indicated  in  the  full-screen 
mode. 


Syntax 

SET  DELIMITERS  on/ OFF 

SET  DELIMITERS  TO  <  expC>  /DEFAULT 

Default 

The  default  for  SET  DELIMITERS  is  OFF  so  that  entry  fields  are  not  enclosed 
by  specified  delimiter  characters.  While  SET  INTENSITY  is  ON,  entry  fields  are 
displayed  in  inverse  video. 

SET  DELIMITERS  ON  uses  colons  (:)  to  set  off  the  field  areas,  unless  you 
choose  a  different  delimiter  with  the  SET  DELIMITERS  TO  command. 


Usage 

SET  DELIMITERS  TO  <  expC>  defines  the  characters  used  to  mark  the  field 
area.  The  character  string  must  be  one  or  two  characters.  If  you  define  one 
character,  that  character  marks  the  beginning  and  the  end  of  the  field.  If  you 
define  two  characters,  the  first  marks  the  beginning  of  the  field  and  the  second 
marks  the  end  of  the  field.  If  you  define  more  than  two  characters,  only  the 
first  two  are  read. 

SET  DELIMITERS  must  be  ON  for  the  symbols  defined  by  SET  DELIMITERS 
TO  to  be  in  effect. 


Examples 

To  mark  the  beginning  and  the  end  of  a  field  with  #: 

.  SET  DELIMITERS  TO 
.  SET  DELIMITERS  CN 

To  mark  the  beginning  of  each  field  with  [  and  the  end  with  ]: 

.  SET  DELIMITERS  TO  ’W 
.  SET  DELIMITERS  CN 

To  reset  the  delimiters  to  colons: 

.  SET  DELIMITERS  TO  DEFALT 
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SET  DELIMITERS 


The  @...GET  command  uses  the  characters  defined  by  the  most  recently  issued 
SET  DELIMITERS  command.  The  following  dBASE  program  file  provides  an 
example: 


SET  TALK  OFF¬ 
SET  DELIMITERS  TO  "  CT 
SET  DELIMITERS  CN 
STORE  "abc"  TO  cne 
STORE  -123'  TO  two 
CLEAR 

3  10,10  GET  cne 
READ 

SET  DELIMITERS  TO  default 

a  11,10  GET  two 

READ 


See  Also 

@,  APPEND,  CHANGE,  EDIT,  INSERT,  READ,  SET  INTENSITY 
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SET  DESIGN 


SET  DESIGN  prevents  transfers  to  design  mode  from  the  dot  prompt  or  from 
the  Control  Center.  It  inactivates  the  Shift-F2  key  combination,  and  prevents 
going  to  the  dot  prompt  from  EDIT/BROWSE  modes. 


Syntax 

SET  DESIGN  ON/ off 
The  default  is  ON. 


Usage 

This  command  is  intended  for  use  by  an  applications  developer.  Its  purpose  is 
to  prevent  a  user  from  getting  into  design  mode  (that  is,  using  Database, 
Report,  Form,  Label,  Query,  and  Applications  from  the  Control  Center)  or  exit¬ 
ing  to  the  dot  prompt  with  the  Shift-F2  key  combination.  Thus,  a  developer  can 
use  the  Control  Center  menu  system  as  the  interface  for  a  limited  application 
and  keep  the  user  out  of  the  functionality  of  dBASE  IV. 
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SET  DEVELOPMENT 


SET  DEVELOPMENT  activates  a  checking  program  in  dBASE  IV  which  com¬ 
pares  the  creation  dates  of  the  compiled  object  (.dbo)  file  with  its  program 
source  (.prg)  file  to  prevent  you  from  using  an  outdated  object  file. 

Syntax 

SET  DEVELOPMENT  on/OFF 

Default 

The  default  for  SET  DEVELOPMENT  is  OFF. 


Usage 

When  ON,  this  command  makes  dBASE  IV  compare  the  creation  date  and  time 
of  the  program  source  (  prg)  file  and  the  compiled  object  (.dbo)  file.  If  the  .dbo 
file  is  older  than  the  .prg  file,  then  dBASE  IV  recompiles  a  new  object  file  from 
the  .prg  file.  If  SET  DEVELOPMENT  is  OFF,  dBASE  IV  does  not  compare  the 
dates  and  times  of  source  and  object  files. 

The  dBASE  IV  internal  editor  (MODIFY  COMMAND)  and  the  Compiler  delete 
the  compiled  .dbo  file  when  its  associated  source  file  is  modified.  Then  the 
newly  modified  source  file  is  automatically  recompiled.  If  you  use  the 
dBASE  IV  internal  editor,  you  do  not  need  the  protection  of  the  SET 
DEVELOPMENT  command.  You  may  selectively  turn  this  date  comparison  on 
for  those  times  when  you  do  use  an  external  editor. 

Users  who  prefer  external  editors  may  find  it  helpful  to  add  this  command  to 
the  Config.db  file  to  avoid  executing  outdated  compiled  files.  See  Chapter  6, 
“Customizing  dBASE  IV,”  for  modifying  the  Config.db  file. 


See  Also 

COMPILE,  MODIFY  COMMAND 
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SET  DEVICE 


SET  DEVICE  determines  whether  @...SAY  commands  are  routed  to  the  screen, 
the  printer,  or  a  file. 

Syntax 

SET  DEVICE  TO  SCREEN/ PRINTER/ FILE  <  filename  > 

Default 

The  default  is  SET  DEVICE  TO  SCREEN. 


With  SET  DEVICE  TO  PRINTER,  the  output  from  @...SAY  commands  is  sent  to 
the  printer.  @...GET commands  are  ignored.  An  @  command  that  specifies 
coordinates  of  lower  values  than  previous  @  commands  results  in  a  page  eject. 

On  some  printers,  @...SAYs  may  not  appear  until  the  print  buffer  is  emptied.  To 
empty  the  buffer,  issue  an  EJECT  command  or  print  a  blank  line. 

You  can  also  send  the  output  from  an  @...SAY  command  to  a  file  by  specifying 
a  new  file  name. 


Example 

To  redirect  @...SAYs  to  a  file: 

%Jd 1,1  SAY  ' This  is  cn  the  first  line.' 
5^5  SAY  'This  is  an  the  fifth  l  tie." 
V^SET  DEVICE  TO  SCREW  .TYPE  Text.txt 
This  is  cn  the  first  line. 


This  is  cn  the  fifth  line. 

See  Also 

@,  EJECT,  SET  FORMAT 
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SET  DISPLAY  TO 


I 


SET  DISPLAY  TO  selects  between  a  monochrome  and  a  color  monitor,  and 
determines  the  number  of  lines  displayed  by  graphics  cards  that  support  both 
25-  and  43-line  screens. 


Syntax 

SET  DISPLAY  TO  MONO/ COLOR/ EGA25/EGA43/M0N043 

Usage 

You  can  use  this  command  only  if  you  have  hardware  that  is  capable  of  sup¬ 
porting  monochrome  and/or  color  display  and  an  EGA  or  equivalent  graphics 
card  that  supports  43-line  display.  If  you  do  not  have  the  required  hardware, 
then  this  command  has  no  effect  on  the  display  mode,  and  gives  an  error 
message. 


y\ 


See  Also 

SET,  SET  COLOR  OF,  SET  COLOR  TO 
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SET  ECHO 


SET  ECHO  displays  command  lines  from  dBASE  IV  programs  on  the  screen 
and/or  the  printer  as  they  are  executed  (from  the  dot  prompt,  or  from  a  dBASE 
program  file). 

Syntax 

SET  ECHO  on/ OFF 

Default 

The  default  for  SET  ECHO  is  OFF. 


Program  instructions  are  not  normally  displayed  during  program  execution. 
SET  ECHO  ON  is  one  of  four  dBASE  IV  commands  that  can  be  used  with 
DEBUG  in  debugging  dBASE  program  execution.  The  other  three  commands 
are  SET  DEBUG,  SET  STEP,  and  SET  TALK. 


See  Also 

DEBUG,  SET  DEBUG,  SET  PRINT,  SET  STEP,  SET  TALK 
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SET  EMACRO 


SET  EMACRO  limits  the  use  of  the  &  (macro)  command  to  legal  dBASE  IV 
expressions. 

Syntax 

SET  EMACRO  on/OFF 

Default 

The  default  for  SET  EMACRO  is  OFF. 


This  command  is  designed  to  speed  the  execution  of  programs  that  do  not  com¬ 
bine  dBASE  commands  with  the  &  macro.  Programmers  who  usually  restrict 
their  &  use  only  to  expressions  do  not  always  need  the  full  macro  capabilities 
of  dBASE  IV. 

When^EMACRO  (expression  macro)  is  ON,  you  can  only  use  the  &  function 
with  legal  dBASE  IV  expresions.  If  you  use  commands  with  the  &  function 
while  SET  EMACRO  is  ON,  an  error  message  appears. 

When  macros  are  limited  to  expressions,  dBASE  IV  does  not  have  to  load  the 
compiler  and  expand  the  macros  it  encounters  in  programming  code.  This 
speeds  program  execution. 

When  you  SET  EM/WCRO  to  OFF,  dBASE  IV  restores  the  full  use  of  the  &  macro 
with  commands. 

This  command  may  be  included  in  your  Config.db  file.  See  Chapter  6, 
“Customizing  dBASE  IV.” 


See  Also 

&,  COMPILE 


■S£T 
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SET  ENCRYPTION 


SET  ENCRYPTION  establishes  whether  a  newly  created  database  file  is 
encrypted  if  PROTECT  is  used.  Without  PROTECT,  SET  ENCRYPTION  has  no 
effect  on  the  encryption  status  of  any  file. 


Syntax 

SET  ENCRYPTION  ON/off 

Default 

The  default  for  SET  ENCRYPTION  is  ON. 

Usage 

This  command  determines  whether  copied  files  (that  is,  files  created  through 
the  COPY,  JOIN,  and  TOTAL  commands)  are  created  as  encrypted  files.  An 
encrypted  file  contains  data  enciphered  into  another  form  to  hide  the  contents 
of  the  original  file.  An  encrypted  file  can  only  be  read  after  the  encryption  has 
been  deciphered  or  copied  to  another  file  in  decrypted  form. 

To  access  an  encrypted  file,  you  must  enter  a  valid  user  name,  password,  and 
group  name  after  the  log-in  screen  prompts.  Your  authorization  and  access  lev¬ 
els  determine  whether  you  can  or  cannot  copy  an  encrypted  file. 

After  you  access  the  file,  SET  ENCRYPTION  OFF  to  copy  this  file  to  a 
decrypted  form.  You  need  to  do  this  if  you  wish  to  EXPORT  the  file  or  use  it 
with  single-user  dBASE  IV.  You  must  also  SET  ENCRYPTION  OFF  to  use  the 
options  of  the  COPY  TO  command. 

NOTE 

Encryption  works  only  with  PROTECT.  If  you  do  not  enter  dBASE  IV 
through  the  log-in  screen,  you  will  not  be  able  to  use  encrypted  files. 
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SET  ENCRYPTION 


Tips 

All  encrypted  files  used  in  an  application  must  have  the  same  group  name. 

Encrypted  files  cannot  be  JOINed  with  unencrypted  files.  Make  both  files  either 
encrypted  or  unencrypted  before  JOINing  them. 

Encrypted  files  must  be  copied  to  new  files  in  decrypted  form  before  they  can 
be  used  with  the  COPY  STRUCTURE  EXTENDED  or  MODIFY  STRUCTURE 
commands.  After  you  copy  the  file  you  may  modify  its  structure.  You  can 
encrypt  the  new  file  with  PROTECT  by  assigning  it  an  access  level. 

In  the  same  way,  you  can  encrypt  files  created  through  the  CREATE  command 
by  assigning  the  files  an  access  level  through  PROTECT. 


See  Also 

PROTECT 
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SET  ESCAPE 


SET  ESCAPE  ON  lets  you  halt  the  processing  of  a  dBASE  IV  program  by  press¬ 
ing  the  Esc  key.  It  lets  you  stop  screen  scrolling  by  pressing  or  Ctrt-S.  It  also 
allows  you  to  record  these  three  keys  with  INKEY(). 


Syntax 

SET  ESCAPE  ON/oEf 

Default 

The  default  for  SET  ESCAPE  is  ON. 

Usage 

With  SET  ESCAPE  ON,  if  you  press  Esc  while  a  command  is  being  processed  or 
a  dBASE  IV  program  is  running,  the  processing  stops  and  dBASE  IV  displays 
the  message: 

—  INTERRUPTED  *** 

Cancel,  Ignore,  Suspend?  (C,  I,  or  S) 

With  SET  ESCAPE  OFF,  the  Esc  key  is  disabled  and  command  processing  can¬ 
not  be  interrupted.  SET  ESCAPE  OFF  also  disables  the  operation  of  Ctrl-S  or  *- 
when  they-are  used  to  temporarily  suspend  scrolling.  ,  . 

A  kg) 

NOTE  A 

When  SET  ESCAPE  is  OFF,  you  cannot  terminate  program  execution 
without  rebooting  your  computer.  Use  SET  ESCAPE  OFF  only  in  tested 
programs  that  do  not  get  in  endless  loops.  Rebooting  your  computer  to 
interrupt  program  execution  may  cause  data  loss. 

See  Also 

INKEYQ,  ON  ERROR,  READKEYQ 
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SET  EXACT 


SET  EXACT  determines  whether  a  comparison  between  two  character  strings 
requires  the  strings  to  be  the  same  length. 

Syntax 

SET  EXACT  on/ OFF 

Default 

The  default  for  SET  EXACT  is  OFF. 

Usage 

If  SET  EXACT  is  OFF,  comparisons  between  character  strings  begin  with  the 
left  character  in  each  string  and  continue  character-by-character  to  the  end  of 
the  string  on  the  right  of  the  relational  operator.  If  the  two  strings  compare 
favorably  up  to  that  point,  the  result  of  the  comparison  is  true  (  T.). 

If  SET  EXACT  is  ON,  the  comparison  of  characters  in  each  string  is  the  same, 
except  that  both  character  strings  must  be  the  same  length  for  the  comparison 
to  be  evaluated  as  true. 

Examples 

Consider  the  two  character  strings  'abc'  and  'abcdef.  First,  compare  the  two 
character  strings  with  SET  EXACT  OFF.  Because  the  character  string  on  the 
right  is  longer  than  the  character  string  on  the  left,  the  two  strings  do  not 
match,  and  the  result  of  the  comparison  is  false  (  F.). 


When  you  reverse  the  positions  of  the  same  two  strings,  the  string  on  the  right 
has  the  identical  starting  characters  as  the  longer  character  string  on  the  left. 
Now  the  two  strings  are  considered  equal. 

?  '&cder=  'ate0 


.T. 


With  SET  EXACT  ON,  the  same  character  strings  are  no  longer  considered 
equal  because  they  do  not  match  exactly: 
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SET  EXCLUSIVE 


SET  EXCLUSIVE  allows  a  user  to  open  a  file  on  a  multiuser  system  for  exclu¬ 
sive  une,  so  that  no  other  user  may  have  any  access  to  that  file. 


Syntax 

SET  EXCLUSIVE  ON/off 

Default 

Tile  default  for  SET  EXCLUSIVE  is  ON. 

Usage 

It  is  not  possible  for  any  other  user  to  read  or  write  to  a  file  which  has  been 
opened  for  exclusive  use. 

Both  the  CREATE  and  the  SAVE  commands  SET  EXCLUSIVE  ON  whenever  you 
use  them. 


See  Also 

COPY  INDEXES/TAG,  INDEX  ON,  PROTECT,  SET  ENCRYPTION 
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SET  FIELDS 


SET  FIELDS  defines  a  list  of  fields  that  may  be  accessed  in  one  or  more  files.  It 
also  determines  whether  that  list  is  used  as  the  default  fields  or  expression  list 
for  dBASE  commands  that  utilize  a  fields  list.  It  sets  read-only  flags,  and  sup¬ 
ports  calculated  fields  and  wildcards  to  match  field  names. 


Syntax 

SET  HELDS  on/ OFF 

SET  HELDS  TO  [<  field  >  [/ R]/  <  calculated  field  id>  ...] 

[,<  field  >  [/R]/ <  calculated  field  id  >  ...] 

/ALL  [LIKE/EXCEPT  <  skeleton  >  ]  [ADDITIVE] 


Default 

The  default  for  SET  HELDS  is  OFF.  It  is  set  ON  when  you  specify  a  fields  list 
with  SET  HELDS  TO.  Do  not  use  SET  HELDS  ON  without  first  specifying  a 
fields  list. 


Usage 

The  field  options  can  include  a  list  of  database  field  names  and  calculated  field 
identifiers.  The  /R  provides  an  optional  read-only  flag. 

The  calculated  field  identifier  name  can  equal  any  valid  dBASE  expression.  For 
example: 

<  Gross  Pay>  =*  Salary  *  Hours 

where  Gross  Pay  is  a  calculated  field  that  is  set  equal  to  the  expression 
Salary  *  Hours. 

The  skeleton  uses  the  wildcard  character  *  for  any  number  of  characters  and  ? 
for  one  character.  ALL  LIKE  selects  fields  that  match  the  skeleton.  ALL 
EXCEPT  selects  the  fields  that  do  not  match  the  skeleton. 

When  SET  HELDS  is  OFF  (the  default),  all  the  fields  of  the  active  database  are 
available.  Fields  in  files  open  in  other  work  areas  are  available  for  display  only 
if  you  specify  their  alias  names. 

SET  HELDS  TO  defines  a  list  of  fields  that  may  be  accessed  in  one  or  more 
files.  It  also  redefines  the  default  field  or  expression  list  used  with  dBASE  com¬ 
mands  which  use  or  display  fields.  The  list  of  fields  specified  by  SET  FIELDS 
TO  is  not  active  unless  SET  FIELDS  is  ON. 

SET  HELDS  TO  -«-*  removes  those  fields  from  the  list  that  belong  to  the  active 
database  file.  SET  HELDS  TO  ALL  includes  all  the  fields  of  the  active  database 
file  that  are  in  the  fields  list. 
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SET  FIELDS 


SET  FIELDS  TO  does  not  impose  any  order  on  the  fields  listed.  It  is  not  case 
sensitive. 


After  a  fields  list  is  set,  additional  or  consecutive  SET  FIELDS  TO  commands 
add  fields  to  the  current  fields  list.  To  include  fields  from  files  in  other  work 
areas,  SELECT  the  work  area  of  the  file  and  use  the  SET  FIELDS  TO  command, 
or  specify  the  file’s  alias  with  the  field  name. 

When  SET  HELDS  is  ON,  the  LIST  STRUCTURE  and  DISPLAY  STRUCTURE 
commands  indicate  the  fields  which  are  in  the  currently  defined  fields  list  with 
the  >  symbol. 


NOTE 

SET  FIELDS  TO  can  define  a  list  of  fields  from  multiple  files,  but  it  does 
not  relate  those  files.  You  must  use  SET  RELATION  to  establish  a  con¬ 
nection  between  files  in  different  work  areas. 


Affected  Commands 


The  field  list  that  you  define  with  the  SET  HELDS  command  is  used  by  all  com¬ 
mands  that  have  a  field  list  option  in  their  syntax.  The  following  commands  use 
the  field  list  specified  by  SET  HELDS  TO: 

CHANGE 

CRE ATE/ MODI FY  VIEW  FROM  ENVIRONMENT 
COPY  TO 

COPY  STRUCTURE 

DISPLAY 

JOIN 

LIST 

TOTAL 


The  SET  HELDS  TO  command  does  not  check  to  see  if  files  are  related;  you 
must  verify  this  yourself. 


The  commands  INDEX,  LOCATE,  SET  HLTER,  and  SET  RELATION  ignore  the 
SET  HELDS  TO  fields  list.  These  commands  can  access  all  fields  in  the  active 
database  file.  To  access  fields  in  files  from  an  unselected  work  area  with  these 
commands,  you  must  specify  the  file  alias  with  each  of  these  fields. 
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SET  FIELDS 


NOTE 

lb  ensure  data  integrity  when  using  view  files,  or  the  S ET FIELDS  and 
SET  RELATION  commands,  you  should  add  records  to  one  database  file 
at  a  time,  with  all  Fields  of  the  database  file  accessible. 


Changes  to  key  information  should  be  done  knowing  that  if  you  change 
parent  key  information  without  also  changing  corresponding  key  infor¬ 
mation  in  related  files,  you  will  lose  the  relation  between  those  records. 
Do  not  construct  Geld  lists  from  multiple  unrelated  Gles  unless  you  have 
a  sound  reason  for  doing  so. 


Accessibility 

If  you  use  multiple  related  files,  the  rules  governing  field  accessibility  are: 

■  Files  unaffected  by  a  SET  FIELDS  TO  command  retain  their  default  fields 
lists. 

■  Fields  from  files  unaffected  by  a  SET  FIELDS  TO  command  are  accessible 
if  an  alias  is  specified,  provided  you  opened  the  file  (with  USE)  after  issuing 
the  SET  FIELDS  TO  command. 

■  Fields  of  the  active  database  file  are  accessible  only  if  they  are  included  in 
the  fields  list. 

■  Fields  in  related  files  are  accessible  if  an  alias  is  specified  when  they  are 
added  to  the  FIELDS  list. 

■  Unless  a  file  has  related  descendants,  fields  beyond  its  own  listed  fields  are 
not  displayed. 

When  referring  to  fields  without  the  use  of  an  alias,  dBASE  resolves  ambiguities 

according  to  these  guidelines: 

■  The  active  database  file  is  searched  first. 

■  If  the  field  is  not  in  the  active  database  file,  the  fields  list  is  searched. 

■  If  a  field  isn’t  found  on  the  fields  list  for  the  active  database  file,  then  fields 
list  entries  for  related  files  are  searched. 
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SET  FIELDS 


Examples 


Display  the  Part_name,  Item_cost,  and  Qtv  -o-x  O  ' 
a  calculated  field  called  Total  to  display  the  produc.  .  i 

ie  Stack 

SET  FIELDS  TO  Ftorturene,  Itmjxxt,  Qty,; 
i  Total  -T  +STR(I tem_past*Qty/r3^D 
. GOTO  10 
UST  TEXT  5 
“  F 

Record#  Part_name  Itaruxst  Qty  Total. 

10  OiAIR,  0E9C  10C0.CD  1  $  IGCD-GD 

11  OiAIR,  SIDE  350.00  2  S  70X00 

12  BOCK  CASE  125.00  1  $  125.00 

13  UVP,  FUXR  150.00  3  $  45D.0C 

14  UW»,  FLOOR  165.00  1  $  165.CD 


Use  the  ALL  LIKE  option  of  SET  FIELDS  TO  on  the  Client  data&asr 
s  only  those  files  that  have  the  string  'name*  in  the  field  name. 


[Use  Cl  ient 
\UST 


Record#  LASTNW€  FIRSTNNE 

1  Wright  Fra-k  L. 

2  Bailey  Sandra 

3  tertinez  Ric 

4  Peters  Kirrberly 

5  Yanada  George  J. 

6  Tinmens  Gene 

7  Belup  Ytri 

8  Beckman  Riener 


See  Also 

CLEAR  HELDS,  CREATE/ MODIFY  VIEW,  CREATE  MEW  FROM 
ENVIRONMENT,  SET  RELATION,  SET  SKIP,  SET  V;  7  0'(t ' 
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SET  FILTER 


SET  FILTER  allows  display  of  only  those  records  of  a  database  file  that  meet  a 
specified  condition. 


Syntax 

SET  FILTER  TO  [FILE  <  filename >  /?]  [<  condition  >  ] 
where  the  filename  is  a  query  (.qry)  file. 


Default 

SET  FILTER  TO  *-*•  without  a  condition  turns  off  the  filter  for  the  active  data¬ 
base  file. 

SET  FILTER  TO  FILE  adds  a  filter  (query)  file  to  a  catalog  if  one  is  open  and 
SET  CATALOG  is  ON. 


Usage 

SET  FILTER  applies  only  to  the  database  file  open  in  the  work  area  where  the 
command  is  issued.  Therefore,  you  can  set  a  different  filter  condition  for  each 
open  database  file. 

All  commands  that  require  a  database  file  to  be  in  USE,  such  as  AVERAGE, 
BROWSE,  EDIT,  and  REPORT,  can  use  conditions  specified  by  SET  FILTER. 

SET  FILTER  TO  FILE  <  filename  >  reads  the  filter  condition  from  a  file  cre¬ 
ated  by  CREATE/MODIFY  QUERY.  If  a  catalog  is  open,  you  can  use  the  catalog 
query  clause  to  display  a  menu  of  all  query  files  for  the  active  database  file. 
dBASE  IV  will  accept  a  dBASE  III  PLUS  query  file;  however,  this  file  cannot  be 
modified  using  dBASE  IV. 

SET  FILTER  TO  <  condition  >  sets  up  a  filter  based  on  a  valid  dBASE  expres¬ 
sion.  The  condition  can  filter  records  in  the  active  database  file  based  on  any 
of  the  allowed  data  types;  for  example,  on  a  character  field,  SET  FILTER  TO 
Lastname  =  'Jones";  or  on  a  date  field,  SET  FILTER  TO  Departure  - 
CTOD('  01/01/  88' ). 

Filters  aren’t  activated  until  after  the  record  pointer  is  moved  within  a  file.  The 
best  way  to  activate  a  filter  setting  is  to  execute  a  GO  RECNO  command  to 
move  the  record  pointer  back  to  the  record  you  started  from. 
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SET  FILTER 


Examples 

To  filter  the  Transact  database  file  for  all  records  whose  Date_trans  filed  is  on 
or  after  3/20/87: 

like  Transact 

JkSET  FILTER  TO  DatK-trans  05/20/8^ 


Lck**-'  ' 


Record*/  CtientJd  0rder_id  Date_trans  Invoiced  TotaLbill 

8  LHHn  87-112  Q3/2Q/87  .T.  703.00 

9  fd£C5  87-113  03/24/87  .T.  125.00 

10  B120G0  87-114  CB/3D/87  .F.  450.CD 

11  ami  87-115  04/01/87  .F.  165.00 

12  A1CE25  87-116  04/10/8 7  .F.  15CD.00 


Specific  record  pointer  positioning  ignores  the  SET  FILTER  TO  conditon.  Con 
t'  ‘'h  the  environment  of  the  preceding  example: 


Record*/  ClientJd  0rder_id  Date_trans  Invoiced  TotaLbilL 
3  CH332  87-107  02/12/87  .T.  1250.00 


See  Also 


CREATE/ MODIFY  QUERY,  SET  DELETED 
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SET  FIXED 


SET  FIXED  is  retained  in  dBASE  IV  for  compatibility  with  dBASE  III  PLUS;  it 
has  no  effect  on  the  number  of  decimals  displayed. 


Syntax 

SET  FIXED  on/OFF 

Default 

The  default  for  SET  FIXED  is  OFF. 


Usage 

This  command  is  not  used  in  dBASE  IV  In  dBASE  IV  the  SET  DECIMALS  com* 
mand  determines  the  number  of  decimal  places  displayed  in  calculation  results. 


See  Also 

SET  DECIMALS 
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SET  FORMAT 


SET  FORMAT  allows  a  form  to  be  used  with  the  READ,  EDIT,  APPEND, 
INSERT,  CHANGE,  or  BROWSE  commands.  The  form  is  stored  as  a  format 
(.fmo)  file.  Format  files  created  using  dBASE  III  PLUS  have  a  .fmt  extension; 
these  files  are  compatible  with  SET  FORMAT  TO  in  dBASE  IV. 

Syntax 

SET  FORMAT  TO  <  format  filename  >  /? 


You  can  use  CREATE/MODIFY  SCREEN  to  create  format  files.  CREATE/ 
MODIFY  SCREEN  first  creates  a  screen  .scr  file,  and  when  you  save  the  .scr 
file,  it  creates  a  format  .fmt  file.  This  format  file  can  be  used  with  SET  FORMAT 
TO  when  you  are  editing  or  changing  records  in  the  associated  database  file. 

The  first  time  you  use  a  .fmt  file,  a  compiled  version  of  it  will  be  created  with  a 
.fmo  extension.  From  that  point  on,  the  .fmo  file  is  used  with  SET  FORMAT  TO. 

The  format  files  use  the  .fmo  extension  as  the  default.  If  you  choose  to  use  your 
own  naming  convention,  you  will  have  to  specify  the  file  extension  each  time 
you  use  the  SET  CATALOG  and  CREATE/MODIFY  SCREEN  commands. 

When  you  want  to  change  a  format  file,  use  the  MODIFY  SCREEN  command 
because  this  command  updates  both  the  .scr  and  .fmt  files.  Do  not  use  the 
MODIFY  COMMAND  text  editor  to  modify  the  format  file,  because  the  changes 
will  not  be  made  to  the  screen  file  and  the  two  files  will  no  longer  correspond 
to  the  same  format. 

The  SET  FORMAT  TO  comm  and  activates  the  format  file  named  in  the  com¬ 
mand  for  use  with  full  screen  editing  commands. 

If  SET  FORMATTO  is  not  used,  APPEND,  CHANGE,  EDIT,  and  INSERT  use  the 
standard  display  and  entry  form  dBASE  IV  provides. 

The  SET  FORMAT  TO  command  updates  a  catalog  if  one  is  open,  and  if  SET 
CATALOG  is  ON. 

If  a  catalog  is  open,  SET  FORMAT  TO  ?  displays  a  directory  of  all  files  with  the 
.fmt  extension  for  the  active  database  file. 

Each  work  area  with  an  open  database  file  can  have  an  open  format  file.  Both 
the  SET  FORMATTO  and  the  CLOSE  FORMAT  commands  close  the  open  for¬ 
mat  file  in  the  currently  selected  work  area. 
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SET  FORMAT 


Programming  Notes 

DO  FORMAT  FILE  works  for  single-page  format  files.  Multi-page  format  files 
work  only  when  the  format  file  is  opened  with  SET  FORMATTO.  If  you  want  to 
use  a  multi-page  format  (.fmt)  file  in  which  the  @...SAY...GETs  continue  on 
from  2  to  32  screen  pages,  include  a  READ  wherever  you  want  a  page  break. 
The  PgDn  and  PgUp  keys  flip  the  pages. 


See  Also 

APPEND,  CHANGE,  CLOSE,  EDIT,  INSERT,  READ,  SET  DEVICE 
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SET  FUNCTION 


SET  FUNCTION  programs  a  function  key.  You  may  associate  up  to  238  charac¬ 
ters  with  each  function  key.  Thereafter,  each  time  you  press  that  function  key, 
thefeequence  o ^characters  programmed  to  that  key'a^e'transmitted  to  the  cur¬ 
rent  input  operation.  ..  . 


Syntax 

SET  FUNCTION  <  expN  >  TO  <  expC> 


Usage 

You  may  program  the  function  keys  by  using  three  different  approaches: 

1.  Use  the  Keys  submenu  of  the  SET  menu  and  assign  new  functions. 

2.  Use  the  SET  FUNCTION  command  at  the  dot  prompt  or  from  within  a 
program. 

3.  Use  the  Config.db  file  to  assign  new  functions  to  programmable  keys.  See 
Chapter  6,  “Customizing  dBASE  IV.” 

The  standard  function  key  assignments  are  listed  in  Table  3-4: 


Table  3-4  Default  function  key  asignments 


Key 

Value 

Key 

Value 

FI 

HELP; 

F6 

DISPLAY  STATUS; 

F2 

ASSIST; 

F7 

DISPLAY  MEMORY; 

F3 

LIST; 

F8 

DISPLAY; 

F4 

DIR; 

F9 

APPEND; 

F5 

DISPLAY  STRUCTURE; 

F10 

EDIT; 

Function  key  FI  is  assigned  to  the  Help  function  and  cannot  be  reprogrammed. 

The  programmable  function  keys  are  F2  through  F10,  Shift-FI  through  Shift-F9, 
and  Ctrl-FI  through  Ctri-FIO. 

Shift-FI  0  and  all  Alt  key  combinations  are  macro  keys  and  cannot  be 
programmed. 

If  you  have  an  enhanced  keyboard  with  function  keys  F11  and  F12,  these  keys 
are  not  programmable  in  dBASE  IV. 
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SET  FUNCTION 


Examples 

Put  a  semicolon  at  the  end  of  the  text  string  of  functions  and  commands  that 
you  assign  to  a  function  key  so  that  the  function  executes  when  you  press  the 
programmed  key  or  key  combination.  Use  quotes  to  delimit  the  beginning  and 
the  end  of  the  text  string. 

To  assign  the  SET  command  to  function  key  FIO,  so  that  pressing  F10  executes 
the  command: 

.  SET  RUCTION  HO  TO  ’SET/' 

To  assign  multiple  commands  to  function  key  F9,  so  that  the  commands 
CLEAR,  USE  Client,  and  LIST  STRUCTURE  are  executed: 


(SET  RNCTICN  F9  TO  ’ CLEAR/USE  CL  ient/UST  STFUCTlfE/’ 
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SET  HEADING 


SET  HEADING  determines  whether  or  not  column  titles  are  shown  above  each 
field  for  DISPLAY,  LIST,  SUM,  and  AVERAGE. 

Syntax 

SET  HEADING  ON/off 


Default 

The  default  for  SET  HEADING  is  ON. 

Usage 

The  commands  DISPLAY,  LIST,  SUM,  and  AVERAGE  display  a  column  title  for 
each  displayed  field,  memory  variable,  or  expression. 

The  column  width  is  the  length  of  the  heading  or  field  width,  whichever  is 
larger. 

Examples 

.  Transact 
.  DISPLAY 


Record#  Client-id 

OrderJd 

Date_trans 

Irwiced 

TotaLbill 

1  A10Q25 

87-105 

01/03/87 

.T. 

1850.00 

.  SET  MINS  OFF 
.  DISPLAY 

1  A10C25 

87-105 

02/03/8 7 

.T. 

1850.00 
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SET  HELP 


SET  HELP  determines  whether  a  pop-up  window  with  dBASE  IV  Help  options 
appears,  when  a  command  is  incorrectly  entered  at  the  dot  prompt. 


Syntax 

SET  HELP  ON/off 

Default 

The  default  for  SET  HELP  is  ON. 


Usage 

If  you  make  an  error  entering  a  command,  the  available  Help  options  appear 
inside  a  pop-up  window.  You  can  select  to  CANCEL  the  command,  to  EDIT  the 
command  syntax  on  the  command  line,  or  to  go  to  the  Help  system  and  look 
up  the  command  syntax. 

See  Also 

HELP,  SET  INSTRUCT 
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SET  HISTORY 


SET  HISTORY  stores  executed  commands  in  a  history  buffer.  SET  HISTORY 
TO  specifies  the  number  of  executed  commands  that  are  stored  in  the  history 
buffer. 

Syntax 

SET  HISTORY  ON/ off 
SET  HISTORY  TO  <  expN> 

Defaults 

The  default  for  SET  HISTORY  is  ON,  and  for  SET  HISTORY  TO  is  20.  You  can 
change  SET  HISTORY  TO  to  any  value  between  0  and  16,000. 


SET  HISTORY  allows  you  to  redisplay,  edit,  or  re-execute  commands  executed 
from  the  dot  prompt.  Commands  executed  inside  a  program  file  are  not  stored 
in  the  history  buffer. 

Use  t  and  i  to  redisplay  commands  you  previously  executed  from  the  dot 
prompt.  Commands  are  displayed  from  most  recent  to  least  recent  as  you  step 
through  the  history  buffer  using  the  T  key.  Commands  stored  in  the  history 
buffer  reside  in  memory.  You  can  LIST  HISTORY  or  DISPLAY  HISTORY  to 
view  all  the  commands  in  the  buffer. 

The  number  of  commands  the  history  buffer  stores  is  determined  by 
SET  HISTORY  TO.  When  this  number  is  reached,  the  earliest  commands  exe¬ 
cuted  are  cleared  from  the  buffer.  Decreasing  the  value  of  SET  HISTORY  TO 
causes  the  number  of  stored  commands  to  be  decreased  to  the  new  value. 

SET  HISTORY  TO  0  clears  all  commands  from  the  history  buffer. 

The  maximum  size  of  the  history  buffer  is  limited  by  the  amount  of  memory 
you  have  available,  and  by  the  memory  occupied  by  other  programs  already 
resident  in  memory,  including  dBASE  IV.  To  calculate  the  amount  of  memory 
that  the  history  buffer  uses,  add  nine  bytes  to  the  number  of  bytes  in  each 
command. 

See  Also 

DISPLAY  HISTORY,  LIST  HISTORY 
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SET  HOURS 


The  SET  HOURS  TO  command  changes  the  time  display  to  either  a  12-hour  or 
24-hour  clock. 

Syntax 

SET  HOURS  TO  [12/24] 

Default 

The  default  for  SET  HOURS  is  12. 


Usage 


When  you  use  the  SET  HOURS  TO  command  to  change  the  display  format,  the 
clock  display  in  all  full  screen  commands  is  changed. 

SET  HOURS  TO  changes  the  clock  screen  display  for  all  screens  that  display 
the  system  clock  such  as  BROWSE  or  Control  Center. 

The  only  allowable  arguments  for  this  command  are  12  and  24.  You  may  enter 
this  command  in  the  Config.db  file  to  make  the  clock  always  display  24  hours. 
See  Chapter  6,  “Customizing  dBASE  IV.” 


Examples 


At  8:00  p.m, 


% 


THUS 
8:00:00  pm 


the  clock  display  changes  as  follows: 
TO  12 


Set  hub 
20:00:00 


7024 


To  return  to  the  default: 
THUS  TO  12 


See  Also 

SET  CLOCK 
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SET  INDEX  opens  the  specified  index  files,  both  index  (.ndx)  and  multiple 
index  (.mdx).  It  may  optionally  specify  the  controlling  index  or  tag  for  an  active 
database  file. 


Syntax 

SET  INDEX  TO  <  list  of  .ndx  or  .mdx  filenames  >  /?  [ORDER 
<  .ndx  filename/TAG>  <  .mdx  tag  name>  [OF  <  .mdx  filename >  ]] 


Defaults 

If  you  do  not  specify  a  file  extension,  SET  INDEX  attempts  to  open  an  .mdx  file 
first,  then  an  ndx  file. 

SET  INDEX  TO  first  closes  all  open  indexes  in  the  current  work  area  except 
the  production  .mdx  file.  Then  it  opens  the  indexes  specified  in  the  TO  phrase. 

SET  INDEX  TO  *♦  without  filenames,  tag  names,  or  options  closes  all  open 
index  files  in  the  current  work  area.  It  is  an  alternate  syntax  for  CLOSE  INDEX. 


Usage 

The  index  given  in  the  ORDER  clause  is  the  master  or  controlling  index.  This 
index  may  be  either  an  index  (.ndx)  file  or  a  tag  name  contained  in  a  multiple 
index  (.mdx)  file.  The  master  index  controls  the  movement  of  the  record 
pointer  in  the  database  file. 

The  FIND  and  SEEK  commands  use  the  master  index  to  locate  matching 
records.  All  other  open  indexes  will  be  updated  when  data  in  their  keys  change, 
but  they  do  not  control  the  record  pointer. 

You  can  optionally  state  the  .mdx  file  which  contains  the  tag  name  by  using  the 
OF  <  .mdx  filename  >  phrase.  If  a  tag  name  is  contained  in  an  .mdx  file  other 
than  the  production  .mdx  file,  or  if  two  open  mdx  files  contain  the  same  tag 
name,  you  should  use  the  OF  phrase  to  indicate  the  correct  index. 

If  only  one  index  is  open,  that  index  controls  the  index  order;  the  ORDER 
clause  is  not  needed. 

Using  the  SET  ORDER  command,  you  can  switch  the  index  file  designated  as 
the  master  index  without  changing  the  open  indexes  or  mdx  files. 

All  open  indexes,  including  the  master  index,  are  automatically  updated  when¬ 
ever  a  change  is  made  to  the  associated  database  file.  All  tag  names  within  open 
.mdx  files  are  also  updated. 
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SET  INDEX 


Record  Pointer 

When  you  issue  SET  INDEX  TO,  the  database  record  pointer  is  positioned  at 
the  beginning  of  the  file  as  determined  by  the  master  index  file. 


Special  Cases 


Although  commands  that  access  the  database  file  show  the  records  arranged  in 
the  master  index  order,  the  physical  order  of  the  records  in  the  file  on  disk  is 
not  changed.  If  you  restore  the  natural  order  of  the  database  file  with 
SET  ORDER  TO  0  or  SET  ORDER  TO  •*■*•,  all  indexes  will  continue  to  be 
updated.  If  you  restore  natural  order  with  SET  INDEX  TO  the  production 
.mdx  file  will  continue  to  be  updated,  but  no  other  indexes  will  be  updated. 
You  will  subsequently  need  to  open  and  REINDEX  all  indexes,  except  for  the 
production  .mdx  index. 

If  you  APPEND  records  to  a  database  file  that  uses  an  index,  new  records  are 
added  to  the  end  of  the  physical  database  file.  After  you  complete  the  field 
entries  in  a  new  record,  the  record’s  key  expression  is  included  in  the  master 
index,  and  the  record  assumes  its  position  in  indexed  order.  All  open  indexes 
are  updated,  as  well  as  all  tags  within  an  open  .mdx  file. 

The  INSERT  command  is  equivalent  to  APPEND  when  an  index  file  is  in  use, 
and  will  add  records  to  the  end  of  the  physical  database  file. 

dBASE  IV  allows  a  maximum  of  47  .mdx  tag  names  or  7  .ndx  files  to  be  open 
simultaneously.  When  an  .mdx  file  is  opened,  all  tags  in  that  file  are  also 
opened. 

Example 

Open  the  Cus_name  index  file  when  the  Gient  database  file  is  open.  Type: 

.  USE  Client 
.  SET  INDEX  TO  CUz_pame 
tester  index:  (is_name 

Open  the  Cus_name  index  file  and  set  the  master  index  to  the  Gient  tag  in  the 


l SET  BCEX  TO  d^name  ORDER  Cl  ient 
tester  index:  Client 


See  Also 

CLOSE,  DELETE  TAG,  DISPLAY  INDEXES,  INDEX,  KEY(),  MDX(),  NDX(), 
ORDER(),  REINDEX,  SET  ORDER,  TAG(),  USE 
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SET  INSTRUCT 


SET  INSTRUCT  enables  the  display  of  information  boxes. 


Syntax 

SET  INSTRUCT  ON/off 

Default 

The  default  for  SET  INSTRUCT  is  ON.  When  ON,  this  command  enables  the 
instruction  boxes  of  the  dBASE  IV  menu  interface.  It  works  with  all  full-screen 
operations,  such  as  APPEND,  BROWSE,  and  EDIT.  When  INSTRUCT  is  OFF,  no 
boxes  are  displayed. 


Usage 

With  SET  INSTRUCT  ON,  the  first  time  you  enter  a  full-screen  command  mod¬ 
ule  from  the  dot  prompt,  the  instruction  box  is  displayed.  Subsequent  entries 
into  that  full-screen  module  during  the  same  dBASE  IV  session  do  not  display 
the  instruction  box. 

From  the  Control  Center,  pressing  **on  a  filenam^displays  an  instruction  box 
containing  the  choices  USE,  DESIGN,  and  d  FILES. /If  INSTRUCT  is  OFF,  press¬ 
ing  **on  a  filename  executes  the  USE  command. 

You  may  use  this  command  to  turn  off  the  instruction  boxes  of  the  dBASE  IV 
menu  interface,  especially  as  you  become  experienced  and  find  that  you  do  not 
need  to  see  them.  You  may  also  disable  the  instruction  boxes  from  the 
Config.db  file.  See  Chapter  6,  “Customizing  dBASE  IV,”  for  information  on  the 
Config.db  file. 
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SET  INTENSITY 


SET  INTENSITY  determines  whether  the  enhanced  screen  attribute  is  used  for 
full-screen  operations  such  as  APPEND  and  EDIT. 


Syntax 

SET  INTENSITY  ON/off 

Default 

The  default  for  SET  INTENSITY  is  ON. 


Usage 

When  SET  INTENSITY  is  ON,  dBASE  IV  displays  @...SAY  commands  with  the 
standard  screen  attribute  and  displays  @...GET  commands  using  the  enhanced 
screen  attribute. 

The  default  standard  attribute  provides  white  letters  on  a  black  background, 
and  the  enhanced  attribute  specifies  black  letters  on  a  white  background.  You 
can  assign  different  display  attributes  to  standard  and  enhanced  displays  with 
the  SET  COLOR  command,  or  by  using  the  full-6creen  SET  command.  The  full¬ 
screen  SET  command  provides  an  easy  way  to  see  your  selections  as  you  make 
them. 

If  SET  INTENSITY  is  OFF,  the  enhanced  screen  attribute  is  not  used.  Instead, 
the  standard  attribute  is  used  for  both  @...GET  and  @...SAY  commands. 


See  Also 

SET,  SET  COLOR,  SET  DISPLAY 
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SET  LOCK 


SET  LOCK  determines  whether  a  lock  is  applied  to  records  in  multi-user  sys¬ 
tems  to  prevent  a  record  from  being  updated  by  more  than  one  user  at  the 
same  time. 


Syntax 

SET  LOCK  ON/off 

Default 

The  default  for  SET  LOCK  is  ON. 

Usage 

Locks  are  applied  to  records  or  files  to  prevent  data  collisions  which  can  result 
when  more  than  one  user  attempts  to  write  to  a  file  or  record  at  the  same  time. 
Locks  permit  read-only  access  by  any  user  to  files  and  records,  even  when  they 
may  be  in  the  process  of  being  updated.  Files  and  records  in  use  are  auto¬ 
matically  locked  when  you  use  any  command  that  updates  or  edits  files  and 
records. 

If  you  SET  LOCK  OFF,  you  can  disable  automatic  locking  for  a  read-only  subset 
of  the  commands  listed  in  Thble  3-5.  These  commands  work  without  locking, 
but  data  integrity  is  not  guaranteed.  Some  of  these  commands  have  two  phases: 
reading  and  writing.  For  these  commands,  SET  LOCK  OFF  applies  only  to  the 
reading  phase.  When  writing  begins,  the  file  is  LOCKed. 
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SET  LOCK 


Table  3-6  Commands  that  automatically  LOCK  fies 


dBASE  Command 

Action 

Level 

Does  SET  LOCK  OFF 
Disable  LOCK? 

@  GET/  READ 

edit 

Record 

No 

APPEND  FROM 

update 

File 

No 

APPEND  [blank] 

update 

Record 

No 

AVERAGE 

read  only 

File 

Yes 

BROWSE 

edit 

Record 

No 

CALCULATE 

read  only 

File 

Yes 

CHANGE/ EDIT 

edit 

Record 

No 

COPY  TAG/ INDEX 

read/write 

File 

Yes  on  read;  No  on  write 

COPY  [STRUCTURE] 

read/write 

File 

Yes  on  read;  No  on  write 

COUNT 

read  only 

File 

Yes 

DELETE/ RECALL 

update 

Record 

No 

DELETE/ RECALL 

update 

File 

No 

EDIT 

update 

Record 

No 

INDEX 

read/write 

File 

Yes  on  read;  No  on  write 

JOIN 

read/write 

File 

Yes  on  read;  No  on  write 

LABEL 

read  only 

File 

Yes 

REPLACE 

update 

Record 

No 

REPLACE  [scope] 

update 

File 

No 

REPORT 

read  only 

File 

Yes 

SET  CATALOG  ON 

catalog 

File 

No 

SORT 

read/write 

File 

Yes  on  read;  No  on  write 

SUM 

read  only 

File 

Yes 

TOTAL 

read/write 

File 

Yes  on  read;  No  on  write 

UPDATE 

update 

File 

No 

When  command  execution  is  complete,  the  file  or  record  is  unlocked. 
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SET  LOCK 


A  record  must  be  locked  before  it  can  be  updated.  In  dBASE  I\^records  are  ^ 

locked  automatically  when  you  press  any  key  other  than  a  cursor  positioning 
key.  dBASE  IV  supports  the  dBASE  III  PLUS  locking  key  combination,  that  is, 

Ctrl-O 

dBASE  IV  also  continues  to  support  control  key  combinations  that  are  used  to 
unlock  records  in  dBASE  III  PLUS,  such  as  Ctrl-C  or  Ctrl-R. 

In  dBASE  IV,  any  time  you  move  the  cursor  to  another  record  (previous  or 
next)  the  record  you  moved  from  is  automatically  unlocked.  The  exception  to 
this  is  the  REPLACE  command.  (See  “Special  Cases”  below.) 

Special  Cases 

If  the  scope  of  the  REPLACE  command  is  a  RECORD,  then  the  lock  is  not 
released  until  you  execute  a  command  other  than  REPLACE.  If  the  next  com¬ 
mand  is  another  replace,  the  record  remains  locked.  This  ensures  that  all 
replace  statements  for  a  given  record  are  complete  before  the  record  is 
released  to  other  users. 

BROWSE  and  EDIT  use  an  automatic  record  lock  on  only  the  record  that  is 
being  modified,  allowing  other  users  access  to  all  the  other  unlocked  records. 

This  feature  is  useful  when  several  users  have  to  check  or  update  records  from 
the  same  database  file;  for  example,  when  many  agents  need  access  to  custo¬ 
mer  records  in  one  database  Hie. 

In  dBASE  IV,  SET  LOCK  does  not  automatically  release  locks  when  multiple 
records  are  locked  using  the  RLOCK()  function.  To  unlock  these,  issue  an 
UNLOCK  command. 
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SET  MARGIN 


SET  MARGIN  adjusts  the  printer  offset  for  the  left  margin  for  all  printed  output. 
The  video  display  is  unaffected. 


Syntax 

SET  MARGIN  TO  <  expN  > 

Default 

The  default  for  the  left  margin  is  zero. 


Usage 

SET  MARGIN  TO  sets  the  margin  for  all  printed  output  from  dBASE  IV. 

The  SET  MARGIN  value  is  the  same  as  the  system  memory  variable  _ploffset. 
Both  of  these  commands  move  the  left  margin.  They  are  not  additive;  the  last 
executed  command  is  the  one  in  effect. 

You  can  include  the  SET  MARGIN  command  in  the  Config.db  file,  to  assign  an 
inital  value  to  the  printer  left  offset.  See  Chapter  6,  “Customizing  dBASE  IV.” 

The  SET  MARGIN  setting  is  added  to  the  left  margin  settings  specified  with 
CREATE/ MODIFY  REPORT  or  LABEL. 


Examples 


To  set  the  left  margin  10  spaces  to  the  right  of  the  first  possible  print  position: 

to  io 

_pLoffset 

10 

The  margin  setting  can  be  changed  with  _ploffset: 


The  last  change  that  was  made  with  _ploffset  is  now  also  the  margin  setting.  If 
you  do  a  LIST  STATUS  command,  you  will  see  that  the  margin  setting  is  now 
equal  to  5.  Until  this  setting  is  changed,  all  output  sent  to  the  printer  will  be 
spaced  5  spaces  to  the  right  of  the  first  possible  print  position. 
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SET  MARK 


SET  MARK  changes  the  delimiter  character  used  to  separate  the  month,  day, 
and  year  in  the  date  display. 

Syntax 

SET  MARK  TO  <  expC> 

Usage 

<  expC>  is  a  single  character  delimited  by  quotes  to  be  used  in  separating  the 
month,  day,  and  year  when  displaying  dates.  The  default  changes  by  country; 
for  it  is  a  slash  (/).  To  restore  the  default  delimiter  character,  type: 


Example 


01.22.88 


See  Also 


DATE(),  DMYQ,  MDY(),  SET  CENTURY,  SET  DATE 
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SET  MEMOWIDTH 


SET  MEMOWIDTH  adjusts  the  width  of  memo  field  output. 


Syntax 

SET  MEMOWIDTH  TO  <  expN  > 

Default 

The  default  memo  width  is  50  characters;  the  minimum  is  5,  and  the  maximum 
is  250.  You  may  customize  this  value  from  the  Config.db  file.  See  chapter  6, 
“Customizing  dBASE  IV.” 

Usage 

Use  SET  MEMOWIDTH  TO  to  alter  the  column  width  of  memo  fields  during 
output. 

See  Also 

MEMLINESQ,  MLINEQ 
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SET  MENU 


The  SET  MENU  command  applies  to  dBASE  III  PLUS  only.  It  determines 
whether  a  menu  of  cursor  movement  keys  appears  with  the  full-screen  com¬ 
mands.  dBASE  IV  uses  the  SET  INSTRUCT  command  to  provide  information 
boxes  about  its  commands. 

Syntax 

SET  MENU  ON/off 

Default 

In  dBASE  III  PLUS,  the  default  for  SET  MENU  is  ON.  SET  MENU  has  no  effect 
in  dBASE  IV. 

Usage 

With  dBASE  IV,  use  the  SET  INSTRUCT  command. 
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SET  MESSAGE 


SET  MESSAGE  displays  a  user-defined  character  string  on  the  bottom  line  of  ,  - 

the  screen  provided  SET  STATUS  is  ON.  '  / 

A  s\ 


Syntax 

SET  MESSAGE  TO  [  <  expC> 

Default 

The  default  is  to  display  on  dBASE  IV  messages.  SET  MESSA3E  TO  — *  resets 
the  message  to  the  default.  The  user-defined  message  does  not  display  unless 
SET  STATUS  is  ON. 

Usage 

The  character  string  can  have  a  maximum  of  79  characters.  If  you  specify  a 
character  string,  it  must  be  delimited  with  any  valid  dBASE  IV  delimiter  (' 

*  ",  or  []).  You  can  also  specify  a  character  type  memory  variable  or  display  a 
field  which  contains  the  literal  text  string. 

In  full-screen  menu  programs,  such  as  ASSIST,  you  can’t  set  your  own  mes¬ 
sage;  the  application  messages  override  it. 

The  message  line  is  in  effect,  as  ong  as  SET  STATUS  is  ON,  when  you  are  enter¬ 
ing  commands  from  the  dot  prompt  and  with  full-screen  editing  commands 
such  as  APPEND,  EDIT,  and  READ,  or  from  within  a  program.  The  message  is 
displayed  centered  on  line  23  of  the  screen,  below  the  status  bar. 


Tips 

If  you  are  using  the  status  bar  and  message  line,  you  should  not  specify  line  23 
in  your  format  file.  When  SET  STATUS  is  ON,  you  can  use  SET  MESSAGE  to 
convey  useful  information  on  line  23. 


See  Also 

SET  STATUS 
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SET  NEAR 


SET  NEAR  positions  the  database  file  to  the  record  immediately  following  the 
potential  location  of  the  sought-after  key  in  that  file. 

Syntax 

SET  NEAR  on/OFF 

Default 

The  default  for  SET  NEAR  is  OFF. 

Usage 

When  SET  NEAR  is  ON,  the  database  is  set  to  the  record  nearest  the  key 
expression  that  was  searched  and  not  found.  When  SET  NEAR  is  OFF,  the  data- 
is  positioned  at  the  end  of  the  Hie  when  a  search  is  unsuccessful. 


n  SET  DELETED  or  SET  FILTER  is  ON,  SET  NEAR  uses(either  orjboth  of 
:  commands  in  selecting  the  record  nearest  to  the  key  expression.  It  does 
ise  records  that  are  marked  for  deletion,  and  it  follows  the  SET  FILTER  TO 
ictions. 
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SET  NEAR 


Example 

To  find  a  Client_id  beginning  with  ’  D"  from  the  Customer  database  file,  or  to 
find  the  first  record  after  the  position  where  "D"  would  occur: 


.  LSE  Customer  ORDER  Cl  ient—id 
Master  index:  CLIENT-ID 
.  LIST  Client-id 

Record#  Ctient_id 

1  AC0GD1 

5  AHD5 

8  A10C25 

7  B12C0D 

3  &HD1 

2  LCQD1 

4  I  nlil> 

.  SETfEM  CN 
.  FW  D 

Find  rot  successful. 

.  ?  EDFO 
F 

.  ?  FOLWO 
F 


You  can  no  longer  use  the  EOF()  function  to  see  if  an  exact  match  has 
occurred;  use  FOUNDQ  to  determine  exact  matches  with  SET  NEAR  ON. 

With  SET  NEAR  ON: 

FOUND()  returns  a  true  (.T.)  if  an  exact  match  has  occurred. 
FOUND()  returns  a  false  (.F.)  for  a  near  match. 

EOF()  returns  a  false  if  the  match  is  a  near  match. 

With  SET  NEAR  OFF: 

FOUNDQ  returns  a  false  if  no  match  occurs. 

EOFQ  returns  a  false  if  no  match  occurs. 


See  Also 

EOFQ,  FIND,  FOUNDQ,  LOCATE,  SEEK,  SEEKQ 
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SET  ODOMETER 


SET  ODOMETER  defines  the  update  interval  of  the  record  counter  for  com¬ 
mands  which  display  a  record  count. 


Syntax 

SET  ODOMETER  TO  [  <  expN  >  ] 

Default 

The  default  interval  is  one,  and  the  maximum  is  200. 


Usage 

SET  ODOMETER  determines  the  interval  at  which  the  record  counter  is 
updated  on  the  screen  for  commands  such  as  COPY  and  RECALL. 

Using  SET  TALK  OFF,  you  can  remove  the  record  counter  from  the  screen 
entirely. 
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SET  ORDER 


SET  ORDER  sets  up  any  open  index  file  or  tag  as  the  master  (controlling) 
index,  or  removes  control  from  all  open  indexes,  without  closing  any  .mdx  or 
.ndx  files. 


Syntax 

SET  ORDER  TO  [  <  expN  >  ]  /  [TAG  <  .mdx  tag>  /  [OF  <  .mdx  filename  >  ]] 


Usage 

SET  ORDER  saves  time  when  you  want  to  reassign  a  controlling  index  file, 
because  it  does  not  close  and  open  the  index  files  or  move  the  record  pointer. 

The  numeric  expression  is  limited  to  a  number  between  0  and  7  corresponding 
to  the  number  of  open  .ndx  files  you  have.  This  optional  number  can  be  used 
only  when  the  active  database  file  does  not  have  an  associated  .mdx  file.  The 
number  you  specify  corresponds  to  the  position  of  a  file  in  the  list  of  index  files 
specified  by  SET  INDEX  TO  or  with  the  USE  command. 

If  you  SET  ORDER  TO  0,  records  in  the  database  file  appear  in  natural  order, 
which  is  the  consecutive  record  number  order  in  which  they  were  created.  You 
must  specify  the  ORDER  by  its  name,  if  ORDER  is  other  than  0,  or  if  you  have 
one  or  more  associated  .mdx  files  open.  The  ORDER  name  is  an  .mdx  TAG 
name  with  .mdx  files,  or  the  filename  of  the  open  .ndx  file. 

The  index  files  are  updated  if  the  index  key  is  changed  or  if  records  are  added 
or  packed. 

If  the  tag  is  contained  in  an  mdx  file  other  than  the  production  mdx  file,  or  if 
an  identical  tag  name  is  in  more  than  one  open  .mdx  file,  you  should  include 
the  optional  OF  <  .mdx  filename  >  phrase  and  indicate  the  .mdx  file  you  want 
to  use. 

After  a  SET  ORDER  command,  activate  the  index  file  by  repositioning  the 
record  pointer  in  the  database  file.  Use  a  command  such  as  GOTO,  FIND,  or 
SEEK. 

Commands  which  process  the  database  file  in  natural  order,  such  as  LOCATE, 
operate  faster  if  no  indexes  are  open.  SET  INDEX  TO  0  before  issuing  any  com¬ 
mand  that  repositions  the  record  pointer  without  using  the  index. 
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SET  ORDER 


Examples 

When  the  database  file,  Customer,  is  opened,  the  master  index  may  be  specified 
to  the  TAG  Client  with  the  ORDER  option  of  USE.  To  change  the  master  index 
from  the  tag  Client  to  the  Cus_name  index  file: 

.  USE  listener  INDEX  CLs_pams  ORDER  CL  ierrt 

tester  index:  CLIENT 

.  SET  ORDER  TO  dS-Pame 

tester  index:  CUSLNAfE 

.  SET  ORDER  TOO 

Database  is  in  natural  order. 


To  set  the  master  index  back  to  the  TAG  Client: 


.  SET  ORDER  TO  Client 
tester  index:  CLIENT 


See  Also 

DISPLAY  INDEXES,  INDEX,  KEY(),  MDX(),  NDX(),  ORDERQ,  REINDEX,  SET 
INDEX,  T4G(),  USE 


LANGUAGE  REFERENCE 


3-75 


J0BNAT1E:  PAGE:  76  SESS:  13  Thu  har  24  17:14:11  1988 


■•tate/di  sk2/al  I  j  obz/CLS_rnanhat/GRP_pianhat/JOB_rnan  langref /DIV_lrchap3 

SET  PATH 


SET  PATH  specifies  the  directory  search  route  that  dBASE  IV  follows  to  find 
files  that  are  not  in  the  current  directory.  dBASE  IV  does  not  use  the  path 
established  by  the  DOS  PATH  command,  nor  does  DOS  use  the  path  that 
dBASE  IV  establishes  with  SET  PATH. 


Syntax 

SET  PATH  TO  [  <  path  list  >  ] 

A  path  list  is  a  series  of  directory  names  separated  by  commas  or  semicolons 
and  up  to  60  characters  long,  which  specifies  the  directory  search  path. 


Defaults 

The  default  is  the  current  directory.  SET  PATH  TO  ♦♦  without  a  path  list 
restores  the  default  path. 


Usage 

The  default  directory  is  where  you  started  dBASE  IV  from,  unless  you  changed 
directories  using  the  DOS  CHDIR  command  or  used  the  SET  DEFAULT  com¬ 
mand  to  specify  a  different  drive. 

SET  PATH  does  not  affect  the  I IR  comm  and  listing.  The  DIR  command  lists 
files  in  the  current  or  specified  directory,  not  in  the  directory  set  through  a 
path.  To  check  a  directory  other  than  the  current  one,  use  the  RUN  command 
and  give  the  path  of  that  directory  to  DOS. 

If  you  wish  to  create  a  new  file  in  a  directory  other  than  the  current  directory, 
specify  the  full  path  name  along  with  the  filename  to  the  CREATE  command. 


Example 

If  the  file,  Program  .dbo,  is  not  found  in  the  DBDATA  subdirectory,  the  next 
directory  to  be  searched  is  the  \dBASE  directory;  if  it  is  still  not  found, 
dBASE  IV  will  search  for  the  file  in  the  root  directory  on  drive  C. 

.  SET  PATH  TO  C:\cBASE\DGMTA 
.  DO  Program 

See  Also 

DIR,  SET  DEFAULT 
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SET  POINT 


SET  POINT  changes  the  character  used  for  the  decimal  point. 

Syntax 

SET  POINT  TO  <  expC> 

Default 

The  default  for  SET  POINT  is  a  period  (.). 

Usage 

Use  this  command  to  change  the  decimal  point  from  the  period  (.)  to  the 
comma(,)  for  international  usage.  You  can  also  specify  any  quoted  single  alpha¬ 
numeric  character.  You  may  not  use  a  digit  or  a  space  for  the  decimal  point. 

To  restore  the  default,  which  is  a  period  (.),  type  SET  POINT  TO 
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SET  PRECISION 


SET  PRECISION  determines  the  number  of  digits  that  dBASE  IV  uses  internally 
in  all  math  operations  that  use  type  N  numbers. 

Syntax 

SET  PRECISION  TO  <  expN> 

where  <  expN>  is  an  integer  between  10  and  20. 


Default 

The  default  for  SET  PRECISION  is  16. 

Usage 

SET  PRECISION  TO  specifies  the  number  of  accurate  digits  used  in  mathemati¬ 
cal  operations. 

The  default  value  for  SET  PRECISION  TO  is  16.  This  may  be  changed  from  the 
dot  prompt  or  from  the  Config.db  file.  See  Chapter  6,  “Customizing  dBASE  IV.” 


See  Also 

SET  DECIMALS 
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SET  PRINTER 


SET  PRINTER  ON  directs  all  output  not  formatted  with  the  @...SAY  command 
to  the  printer. 

SET  PRINTER  TO  redirects  output  to  a  local  printing  device,  or  to  a  shared 
network  printer.  On  a  network,  SET  PRINTER  TO  also  signals  the  file  server  to 
print  the  next  printjob. 

Syntax 

This  command  has  four  forms: 

SET  PRINTER  on/OFF 
The  default  is  OFF. 

SET  PRINTER  TO  <  DOS  device  > 

The  default  is  LPT1 

SET  PRINTER  TO  \\<  computer  name  >  \<  printer  name  >  = 

<  destination  >  /\\S POOLER/ \\CAPTURE 

SET  PRINTER  TO  FILE  <  filename  > 


Usage 


The  first  three  forms  of  this  command  are  used  to  direct  or  redirect  printer  out¬ 
put  to  different  devices.  The  fourth  syntax  is  a  feature  of  dBASE  IV,  and  pro¬ 
duces  printer  formatted  files. 

Redirecting  Screen  Output  to  Printer 

When  SET  PRINTER  is  ON,  all  screen  output,  including  TALK,  LIST,  and  ?  is 
routed  to  the  printer. 

Use  SET  DEVICE  TO  PRINTER  to  direct  @...SAY  commands  to  the  printer.  SET 
PRINTER  ON  does  not  affect  @...SAY  commands. 

Printing  to  a  Local  Device 

Use  SET  PRINTER  TO  <  DOS  device  >  to  send  printed  output  to  a  local 
printer.  This  can  be  any  one  of  the  three  parallel  ports  (LPT1,  LPT2,  LPT3)  or 
oni  ports  (COM1  or  COM2).  For  example: 


sends  print  output  to  the  printer  connected  to  parallel  port  2. 
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SET  PRINTER 


The  SET  PRINTER  TO  command  is  used  to  reset  the  DOS  default  device.  In  a 
network  environment,  dBASE  IV  signals  the  file  server  to  execute  the  most 
recent  printjob.  Therefore,  you  can  use  SET  PRINTER  TO  <  DOS  device  > 
command  to  initiate  spooling  and  reset  the  default  DOS  device.  This  form  of 
the  command  empties  the  print  spooler  and  resets  the  print  destination  to  its 
default,  or  to  another  destination.  For  example: 

.  SET  PRINTER  TO  LPT1 

resets  the  print  output  to  the  local  parallel  printer. 

Printing  on  a  Network 

To  use  the  IBM  PC  and  3Com  networks: 


.SET  PRINTER  TO  1  \<carxjter  name>\<printer  rem>  =  <dsstiraticn> 


<  computer  name>  is  the  network-assigned  name  for  the  network  file  server. 

<  printer  name>  is  the  network-assigned  name  for  the  printer  used  on  the 
IBM  network.  There  may  be  more  than  one  of  each  on  a  given  network. 

<  destination  >  identifies  the  installed  shared  printer  as  LPT1,  LPT2,  or  LPT3. 
The  shared  printer  may  be  at  the  logged  user’s  workstation  or  at  a  remote 
workstation.  For  example: 

yS 

.SET PRINTER  TO  \^ER/ER\EPSCN=LFT1 

sends  output  to  a  shared  Epsot  printer  off  the  file  server  designated  as  LPT1  on 
that  server. 


To  use  the  Novell  network,  type: 

T  PRINTER  TO  WSPOOLERA  \CAPTIFE 


Use  this  form  of  the  command  if  you  have  not  previously  executed  a  command 
to  direct  output  to  the  network  printer.  SPOOLER  and  CAPTURE  are  equivalent 
terms;  both  are  supported.  Use  only  one  of  them  in  your  commands. 


Each  time  you  direct  print  output  to  a  different  printer  or  spooler,  you  can 
reset  the  default  by  setting  the  printer  to  the  default  printer  name: 


T  PRINTER  TO  <BOS  defauL  t> 
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SET  PRINTER 


Printing  to  a  File 

This  command  is  used  to  produce  a  printer  formatted  file  which  you  can  send 
to  the  printer  for  which  it  was  formatted.  If  this  file  is  produced  with  the  print 
driver  Ascii. dpr,  then  you  get  an  ASCII  text  file  that  is  suitable  for  sending  to 
any  line  printer,  or  via  a  telecommunications  link. 

To  create  a  printer  formatted  file,  type: 


dBASE  IV  assigns  the  default  extension  of  .prt  to  files  formatted  for  the  printer, 
unless  you  use  the  Ascii. dpr  print  driver,  in  which  case  they  are  assigned  the 
default  extension  of  .txt. 

To  get  a  text  file,  assign  the  Ascii. dpr  print  driver  by  typing: 


Now,  when  you  send  the  output  to  a  file,  the  result  will  be  an  ASCII  file. 

To  get  a  file  formatted  for  a  specific  printer,  for  example,  the  Hewlett-Packard 
LaserJet,  assign  the  print  driver  by  typing: 


Next,  select  the  file  you  would  like  to  print  on  the  LaserJet  and  send  the  output 
to 


The  resulting  file  will  be  Filename. prt  and  will  be  imbedded  with  the  printer 
control  codes  for  the  LaserJet.  This  file  can  be  sent  directly  from  the  DOS 
prompt  of  any  PC  connected  to  a  LaserJet  printer. 

Assuming  the  printer  formatted  file,  Filename. prt  is  on  a  diskette  in  the  A  drive, 
and  the  LaserJet  is  attached  to  serial  port  COM1,  from  the  default  DOS  prompt 
type: 

COPY  A: Filename. prt  COM1 

The  printed  output  will  be  formatted  correctly  for  the  LaserJet.  Notice  that  you 
are  copying  a  file  and  not  using  the  DOS  print^driver Qtility^ffio  not  use  the 
DOS  PRINT  command,  as  this  will  print  the  imbedded  control  codes  along  with 


the  text  and  produce  unusable  output. 
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SET  PRINTER 


SET  PRINTER  TO  FILE  remains  in  effect  until  you  issue  a  SET  PRINTER  TO 
command  and  redirect  output  to  the  local  DOS  device  or  to  the  network 
spooler.  When  you  restore  the  default  device,  you  might  need  to  change  the 
print  driver  used  with  SET  PRINTER  TO  FILE  if  this  is  different  from  the 
default  driver.  Change  your  printer  driver  by  setting  _pdriver  equal  to  the  name 
of  the  print  driver  you  want. 


Examples 

The  following  commands  spool  the  output  of  report  Names  to  the  network 
printer  (parallel  printer  number  1)  attached  to  the  server  named  ASERVER: 

ftfajgT  PRINTER  TO  1  \AS£R/ER\PRINTER=LPrn 
’M&PCRT  FORM  Erplcyee  TO  PRINTER 
[f^SET  PRINTER  TO  LFTi 

The  first  command  redirects  LPT1  to  the  network  printer;  the  second  sends  the 
output  to  the  spooler;  the  third  sends  the  spooled  output  to  the  printer  and 
resets  the  network  printer. 


% 


See  Also 


?/??,  ???,  SET  DEBUG,  SET  DEVICE 
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SET  PROCEDURE 


SET  PROCEDURE  opens  a  named  procedure  file. 


Syntax 

SET  PROCEDURE  TO  [  <  procedure  filename  >  ] 


Defaults 

The  procedure  filename  must  include  the  drive  location  if  the  named  file  is  not 
on  the  default  drive  or  in  a  dBASE  search  path. 

If  you  do  not  specify  a  file  extension  for  the  procedure  filename,  dBASE  IV 
assumes  an  object  procedure  file  with  the  .dbo  extension.  Compiled  dBASE  IV 
procedure  files  use  the  .prc  extension  and  compiled  dBASE  IV/SQL  procedure 
files  use  the  .prs  extension.  If  dBASE  IV  cannot  find  the  specified  compiled  file, 
it  will  compile  the  source  file  to  produce  a  .dbo  file. 

SET  PROCEDURE  TO  <  procedure  filename  >  opens  the  specified  procedure 
file.  SET  PROCEDURE  TO  ♦♦  or  CLOSE  PROCEDURE  closes  the  current  proce¬ 
dure  file. 


Usage 

Aprocedure  file  may  contain  a  theoretical  maximum  of  1,170  procedures 
(routines);  however,  available  RAM  may  limit  this  number.  The  command 
PROCEDURE  marks  the  beginning  of  each  new  routine.  Only  one  procedure 
file  may  be  open  at  a  time. 

Any  program  can  have  procedure  files  in  it. 


Examples 

The  following  program  and  procedure  files  illustrate  the  use  of  procedures.  For 
example,  you  could  create  the  following  program  which  opens  a  procedure  file 
and  executes  the  three  procedures  within  that  file: 


*  Setproc.FRG  -  Demers trates  SET  PRDCEDLFE  TO 


SET  FROCEDIFE  TO  Proctest 
DO  Proci 
DO  Proc2 
CUKE  PROCEDURE 
*  ECP:  Setpnx.prg 


SS  Cpen  the  procedure  file. 
8&  Execute  procedure  1 . 

8&  Execute  procedure  2. 

8&  Close  the  procedure  file. 


LANGUAGE  REFERENCE 


3-83 


J08NAME:  PAGE:  84  SESS:  13  Thu  Mar  24  17:14:11  1988 


®tate/di  sk2/at  I  j  obz/CLS_inanhat/GRP_jnanhat/JOB_^ian  langref  /DIV_lrchap3 

SET  PROCEDURE 


The  setup  of  the  Proctest  procedure  file  (which  is  also  a  dBASE  program  file) 
could  be  as  simple  as  the  following: 

*  Proctest.prc  -  ProcecLres 
PROCHXRE  Procl 

?  "This  is  a  message  fran  FYocI  of  Proctest.prc." 

RETUW 

*  BDP:  Procl 
PRDCHXPE  Proc2 

?  "This  message  is  in  Proc2  of  Proctest.prc." 

DO  Proc3 
RETURN 

*  HP:  Pnoc2 
PROCEDURE  Proc3 

?  "This  message  is  in  Proc3  of  Proctest.prc  arrf 
?  "  mbs  called  fran  Proc2  of  Proctest.prc." 

RETURN 

*  HP:  Pnoc3 

*  HP:  Proctest.prc 

To  execute  the  procedure  (if  both  the  dBASE  program  file  and  the  procedure 
file  are  in  the  default  directory  or  along  the  path  specified  by  SET  PATH  TO), 
you  would  type: 

.  DO  Setproc 

This  is  a  message  fran  Procl  of  Proctest.prc. 

This  message  is  in  Proc2  of  Proctest.prc. 

This  message  is  in  Proc3  of  Proctest.prc  and 
was  called  fran  Proc2  of  Proctest.prc. 


See  Also 

COMPILE,  DO,  PARAMETERS 
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SET  REFRESH 


SET  REFRESH  specifies  the  time  interval  between  file  checks,  to  determine  if  a 
record  has  changed  in  a  file  that  is  being  BROWSEd  or  EDITed  on  a  network. 

Syntax 

SET  REFRESH  TO  <  expN  > 

Default 

The  default  for  SET  REFRESH  is  zero. 


Usage 

You  can  enter  this  command  from  the  dot  prompt  before  beginning  a  BROWSE 
session,  or  set  the  refresh  interval  from  Config.db.  At  the  end  of  each  refresh 
interval,  dBASE  IV  checks  all  records  that  are  being  BROWSEd  on  the  network 
and  displays  any  updated  information. 

The  refresh  interval  works  differently  with  EDIT.  If  the  file  is  being  EDITed  and 
if  there  is  no  keyboard  input  for  the  duration  of  the  refresh  interval,  dBASE  IV 
checks  the  files  that  are  being  edited  on  the  network  and  updates  the  screen 
being  edited  with  any  changes  it  finds. 

The  numeric  expression  is  a  time  interval  expressed  as  seconds.  The  range  is 
from  1  to  3,600  (one  hour),  and  the  default  is  0. 
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SET  RELATION 


SET  RELATION  links  two  open  database  files  according  to  a  key  expression  that 
is  common  to  both  files. 


Syntax 

SET  RELATION  TO 

SET  RELATION  TO  <  exp  > 

SET  RELATION  TO  <  expNl  >  INTO  <  alias  1  > 

[<  expN2>  INTO  <  alias  2>  ...] 


Defaults 

SET  RELATION  TO  •*-*,  without  any  additional  parameters,  removes  the  relation 
from  the  currently  selected  work  area. 


Usage 

SET  RELATION  links  the  active  database  file  to  an  open  database  file  in  another 
work  area.  The  INTO  file  is  identified  by  its  alias.  The  active  database  file  that 
controls  the  relation  is  referred  to  as  the  parent  file.  The  file  which  is  linked  to 
the  parent  file  by  a  relating  expression  is  referred  to  as  the  child. 


Options 

With  the  numeric  expression  option,  the  active  database  is  always  linked  to  the 
record  number  in  the  file  specified  by  the  numeric  expression.  The  linked  file 
must  not  be  indexed.  Typically,  the  numeric  expression  will  be  the  RECNOQ 
function.  This  causes  record  1  in  the  parent  file  to  be  linked  to  record  1  in  the 
child,  record  2  in  the  parent  to  record  2  in  the  child,  and  so  on. 


Record  Pointer 

If  a  matching  record  cannot  be  found  in  the  linked  file,  the  linked  file  is  posi¬ 
tioned  at  the  end  of  the  file  (a  blank  record),  and  EOF  is  true  (.T.). 


Tips 

You  can  save  a  working  environment,  including  relations,  with  CREATE  VIEW 
<  .vue  filename  >  FROM  ENVIRONMENT.  Remember  that  CREATE/ MODIFY 
VIEW  is  available  to  you  as  a  menu-driven  command  for  linking  files.  It  also 
allows  you  to  save  relations  to  a  vue  file. 
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SET  RELATION 


Examples 

lb  relate  the  Transact  database  file  into  the  Customer  database  file,  link  the  two 
files  on  the  Client_id: 


.  SELECT  1 

.  USE  Qjstamer  ORDER  CL  ient_id 
Master  index:  CLIENtiD 
.  SELECT  2 
.  USE  Transact 

.  SET  RELATION  TO  CL  ientjd  INTO  Customer 
.  LIST  NEXT  5  CL  ientjd,  CUstcmer->CLient,  Dat^Jrans,  TotaLbiLL 


Record# 

Cl  ientjd 

Custaner->Client 

DateJrans 

TotaLbill 

1 

A10025 

RflJC  EVB/TS 

02/QV87 

1850.m 

2 

C00CD1 

L.G.  BLLM  &  ASSOC. 

02/10/87 

12m.CD 

3 

QUITE 

TIftCNS  &  CASEY,  LTD. 

02/12/87 

1250.CD 

4 

cooroi 

L.G.ELLM  &  ASSOC. 

02/23/87 

1250.00 

5 

L00DD1 

BAILEY  &  BAILEY 

03/09/87 

415.00 

To  relate  a  database  file  into  multiple  database  files,  continue  with  the  environ¬ 
ment  from  the  previous  example: 


.  SELECT  3 

.  USE  Items  CRDER  Ordered 
Master  index:  CRDERJD 
.  SELECT  2 

.  SET  RELATION  TO  CL  ientjd  INTO  Customer,  Order_id  INTO  Items 
c  LIST  TEXT  5  Custcmer->CL  i&it,  Date_trans,  Items-^Rartname 


Record# 

1 

2 

3 

4 

5 


CLstcmer-Xtient 
RELIC  EVBJTS 
L.  G.  ELLM  &  ASSOC. 
TWINS  &  CASEY,  LTD. 
L.G.BLUM  &  ASSOC. 
BAILEY  S  BAILEY 


DateJrans 

02/03/87 

02/10/87 

02/12/87 

02/23/87 

03/09/87 


Itens->flart_rBme 
SOFA,  6-FOOT 
SOFA,  8-fCOT 
CHAIR,  DE3C 
CHAIR,  DE9C 
TABLE,  B© 
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SET  RELATION 


To  establish  a  chain  relation  of  the  Items  database  file  into  the  Orders  database 
file  into  the  Customer  database  file,  continue  with  the  previous  example’s 
environment: 

.  SET  RELATION  TO  CL  ientud  INTO  CLstarer 
.  SET  ORDER  TO  Order_id 
Master  index:  CRDER_ID 
.  SELECT  3 

.  SET  INDEX  TO  S&  Set  the  file  back  to  rahraL  order. 

.  SET  RELATION  TO  OrderJd  INTO  Transact 
.  LIST  NEXT  5  Part-Pem,  Transact-SOateJrans,  Custamtr->CL  ient 


Record# 


Transact->Oate_trars 


Qjstaner->CLient 


( 


1  SOFA,  6-RUT  02/05/87 

2  SOFA,  6-ROT  02/03/8 7 

3  SOFA,  8-ROT  CE/1Q/87 

4  CHAIR,  DESK  02/12/87 

5  CHAIR,  DESK  02/23/87 


RELIC  EVENT'S 
RELIC  EVENTS 
L.  G.  BLLM  &  ASSOC. 
TIMING  &  CASEY,  LTD. 
L  G  BLUM  &  ASSOC. 


See  Also 


CREATE/ MODIFY  VIEW,  SET  FIELDS,  SET  SKIP,  SET  VIEW 
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SET  REPROCESS 


SET  REPROCESS  sets  the  number  of  times  dBASE  IV  tries  a  network  file  oi 
record  lock  command  before  producing  an  error  message. 


Syntax 

SET  REPROCESS  TO  <  expN> 

Default 

The  default  is  zero. 


Usage 

This  command  is  valid  only  in  programs,  or  from  the  Config.db  file.  Use  this 
command  in  a  local  area  network  to  change  the  command  execution  process.  A 
record  or  a  file  may  be  in  use  on  the  network,  and  several  retries  may  be 
required  to  access  it.  You  can  request  from  1  to  32,000  retries  with  the 
<  expN  >  option.  If  you  use  a  negative  value,  you  can  set  up  a  checking  condi¬ 
tion  with  infinite  tries. 

If  the  program  cannot  lock  the  record  after  the  specified  number  of  retries,  and 
you  are  in  a  full-screen  command  such  as  BROWSE,  EDIT  or  READ,  dBASE  IV 
displays  a  Please  Writ,  another  user  has  locked  this  record  or  file  on  the 
message  line. 


See  Also 

FLOCK (),  NETWORKQ,  RLOCKQ/LOCK,  UNLOCK 
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SET  SAFETY 


SET  SAFETY  prevents  you  from  unintentionally  overwriting  an  existing  file  by 
providing  a  screen  message  that  asks  you  to  verify  that  you  really  want  to  write 
over  the  file. 

Syntax 

SET  SAFETY  ON/off 

Defaults 

The  default  for  SET  SAFETY  is  ON. 


Usage 

With  SET  SAFETY  ON,  if  a  file  with  the  same  name  as  the  one  you’re  creating 
already  exists,  dBASE  IV  displays  an  error  box  File  already  exists  Overwrite 
Cancel.  The  selection  is  on  Overwrite. 

If  you  want  to  overwrite  the  existing  file,  press  *-*.  The  existing  file  is  then  over¬ 
written,  and  the  data  it  contains  is  lost.  If  you  don't  want  to  overwrite  the  exist¬ 
ing  file,  move  the  selection  bar  over  to  Cancel  and  press  ♦*.  Then,  give  a  new 
name  to  the  file  you  are  creating. 

With  SET  SAFETY  OFF,  you  can  overwrite  files  or  destroy  data  without  receiv¬ 
ing  a  warning. 


See  Also 

COPY,  COPY  FILE,  INDEX,  JOIN,  SAVE,  SORT,  TOTAL,  UPDATE,  ZAP 
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SET  SCOREBOARD 


If  SET  SCOREBOARD  is  ON  and  SET  STATUS  is  OFF,  then  dBASE  IV  displays 
the  scoreboard  keyboard  indicators  on  line  1  of  the  screen. 

Syntax 

SET  SCOREBOARD  ON/off 

Default 

The  default  for  SET  SCOREBOARD  is  ON. 


Usage 

With  SET  SCOREBOARD  ON  and  SET  STATUS  OFF,  you  see  scoreboard  indica¬ 
tors  on  line  1  of  the  screen.  These  include  Del  to  indicate  that  a  record  is 
marked  for  deletion.  Ins  for  insert  mode,  Caps  for  the  caps  lock  mode,  and 
Nam  for  the  numeric  pad  lock  indicator. 

With  SET  STATUS  ON,  when  you  enter  a  value  that  is  outside  a  specified  range, 
the  correct  RANGE  is  displayed  on  the  message  line.  If  you  turn  STATUS  OFF 
while  the  message  is  displayed,  the  message  moves  to  the  scoreboard  area  on 
line  1  of  the  screen. 

If  SET  STATUS  is  on,  then  these  indicators  are  displayed  on  the  status  bar,  and 
SET  SCOREBOARD  has  no  effect. 

With  both  SET  SCOREBOARD  OFF  and  SET  STATUS  OFF,  dBASE  IV  does  not 
display  these  indicators. 


See  Also 

SET  STATUS 


LANGUAGE  REFERENCE 


3-91 


JOBNAHE:  PAGE:  92  SESS:  13  Thu  Mar  24  17:  14:  11  1988 

®tate/d  i  sk2/a  I  I  j  obz/CLS_jnanhat/GRP_pianhat/JOB_man  I  angref  /0IV_lrchap3 
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SET  SEPARATOR 


SET  SEPARATOR  changes  the  symbol  used  for  the  numeric  separator  from  the 
comma  (,),  which  is  the  U.S.  convention,  to  a  specified  character. 

Syntax 

SET  SEPARATOR  TO  [  <  expC  >  ] 

Default 

The  default  for  SET  SEPARATOR  is  the  comma. 


Usage 


The  separator  character  defined  as  <  expC>  can  be  only  one  character  long. 
The  default  may  be  changed  in  the  Config.db  file.  See  Chapter  6,  “Customizing 


dBASE  IV.” 

Examples 

period  separators,  and  comma  decimal  mark: 


1 


See  Also 


SET  POINT 
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SET  SKIP 


SET  SKIP  supports  multiple  detail  record  handling  in  database  files  linked  with 
the  SET  RELATION  command.  It  allows  you  to  access  all  records  in  the  linked 
files  that  match  a  particular  key. 


Syntax 

SET  SKIP  TO  [  <  alias  namel  >  [,<  alias  name2  >  ...]] 


Usage 

This  command  is  effective  only  if  a  SET  RELATION  command  has  been  used  to 
link  related  database  files.  It  allows  the  record  pointer  in  specified  related  data¬ 
base  files  to  be  updated  before  the  active  database  file  record  pointer  is 
changed.  This  lets  you  access  multiple  occurrences  of  the  same  key  in  linked 
files. 

When  you  update  database  files  linked  in  a  relationship  chain,  the  commands 
SET  RELATION  TO  and  SET  SKIP  determine  the  sequence  of  the  updates  to  the 
database  files. 

A  comm  and  that  advances  the  record  pointer  begins  its  updates  in  the  database 
file  which  is  the  last  in  the  relationship  chain.  The  record  pointer  is  updated  in 
each  database  file,  moving  up  the  relationship  chain  towards  the  parent  file. 

The  active  database  may  be  left  off  the  relation  chain;  it  will  be  updated  last 
even  if  it  is  not  specified  with  the  SET  SKIP  command. 

SET  SKIP  affects  all  commands  that  have  FOR  and  WHILE  clauses. 

This  command  also  changes  the  display  of  data  from  related  database  files.  Mul¬ 
tiple  records  from  related  files  can  be  displayed  without  displaying  duplicate 
data  in  the  parent  file. 
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SET  SKIP 


Example 

Use  SET  SKIP  to  display  all  matching  records  in  related  database  files. 
.  SELECT  3 

.  USE  Items  ORDER  OrdsrJd 
fester  index:  ORDERED 
.  SELECT  2 

.  USE  Transact  ORDER  CL  ientJd 
fester  index:  CUENT_ID 
.  SET  RELATION  TO  Orderjd  INTO  Items 
.  SELECT  1 

.  USE  CLstcner  SS  fibster  database  file. 

.  SET  RELATION  TO  CL  ientJd  INTO  Transact 
.  SET  SOP  TO  Items >  Customer,  Transact 
.  LIST  CL  ient,  2-ZOrderJd,  Items-Jfbrtume 


Record#  Client 


->Crder_id  Items->Rirt_reme 


1  VRIGHT  &  SCNS,  LTD. 


2  BAILEY  &  BAILEY  87-109 

2  BAILEY  S  BAILEY  87-112 

3  L.  G.  ELLM  &  ASSOC.  87-105 

3  L  G.  BLLM  &  ASSOC.  87-10B 

3  L.  G.  BLLM  &  ASSOC.  87-115 

4  SAWTER  LXNjFELLOUS  87-111 

5  SMITH  ASSOCIATES  87-113 

6  TIW36  &  CASEY,  LTD.  87-107 

6  TIWCNS  &  CASEY,  LTD.  87-110 

6  TI MNS  ft  CASEY,  LTD.  87-1 1C 

7  VOLTAGE  HURT'S  87-114 

8  RELIC  EVBfTS  87-1Q5 

8  RELIC  EVENTS  87-105 

8  RELIC  EVBTTS  87-105 

8  RELIC  EVWTS  87-116 

8  RELIC  EVBVTS  87-116 

8  RELIC  EVWTS  87-116 


TABLE,  0® 
CHAIR,  SIDE 
SOFA,  8-FOOT 
CHAIR,  DESK 
LA*3,  FLOOR 
CHAIR,  DESK 
BOCK  CASE 
CHAIR,  DESK 


DESK,  BGC.  5-ROT 
FILE  CABINET,  2-DRAUER 


U¥f»,  FLOOR 
SOFA,  6-FOOT 
SOFA,  6-ROT 
LAW3,  FLOOR 
CHAIR,  DESK 


FILE  CABINET,  2  DRAWER 
FILE  CABINET,  4  DRAWER 
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SET  SPACE 


SET  SPACE  lets  the  ?  and  ??  commands  print  a  space  between  the  printed 
expressions. 


Syntax 

SET  SPACE  ON/off 

Default 

The  default  for  SET  SPACE  is  ON. 


This  command  introduces  an  extra  space  between  fields  in  the  ?  or  the  ??  com¬ 
mands.  Use  commas  between  the  printed  expressions  you  want  to  separate  with 
SET  SPACE. 


Example 

.  ram  =  'Susarf 
Susan 

.  city  -  "Bostcrf 
Boston 

.  ?  mm,  city 
Susan  Boston 
.  SET  SPACE  OFF 
.  ?  rme,  city 
SusarBastcn 
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SET  SQL 


SET  SQL  activates  the  SQL  mode  in  dBASE  IV.  Once  SQL  is  activated,  only 
SQL  commands  and  a  subset  of  dBASE  IV  commands  are  allowed. 


Syntax 

SET  SQL  on/OFF 

Default 

The  default  for  SET  SQL  is  OFF. 


Usage 

SET  SQL  ON  can  be  issued  from  the  dot  prompt.  The  dot  prompt  changes  to 
the  SQL  prompt,  and  only  valid  SQL  statements  can  be  used. 

SET  SQL  OFF  can  be  issued  while  in  SQL  mode  from  the  SQL  prompt,  and  the 
prompt  changes  to  the  default  dot  prompt.  When  SQL  is  OFF,  only  valid 
dBASE  IV  commands  and  functions  are  allowed. 
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SET  STATUS 


SET  STATUS  determines  whether  the  status  bar  displays  at  the  bottom  of  the 
screen  when  you  are  working  from  the  dot  prompt,  from  within  a  program,  and 
in  full-screen  editing  commands  such  as  APPEND,  EDIT,  and  READ. 

Syntax 

SET  STATUS  ON/off 

Default 

The  program  default  for  SET  STATUS  is  OFF.  However,  STATUS  is  set  ON  by  the 
Config.db  Hie  which  is  loaded  during  installation  of  single-user  dBASE  IV.  If  the 
Config.db  file  is  not  used,  the  SET  STATUS  defaults  to  OFF. 

Usage 

When  SET  STATUS  is  ON,  the  status  bar  displays  the  command  name,  the  file  in 
use,  and  the  record  number  out  of  the  total  number  of  records.  When  STATUS 
is  OFF,  this  information  is  not  displayed. 

If  both  STATUS  and  SCOREBOARD  are  ON,  scoreboard  information  about  the 
keyboard  modes  is  displayed  on  the  status  bar.  When  SET  STATUS  is  OFF,  the 
scoreboard  information  displays  at  the  top  right  of  the  screen. 

When  you  issue  commands  that  cause  information  on  the  status  bar  to  change, 
the  status  bar  is  updated. 

Tips 

SET  STATUS  ON  can  be  used  with  SET  FORMAT  and  READ.  However,  be  sure 
not  to  specify  fields  or  text  below  line  21  (or  line  41  in  EGA43  mode).  If  you 
use  the  area  of  the  screen  below  line  21,  your  programs  or  data  will  overwrite 
the  status  bar  and  the  message  line. 

See  Also 

SET  MESSAGE  TO,  SET  SCOREBOARD 
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SET  STEP 


SET  STEP  halts  the  execution  of  a  program  after  each  instruction.  It  allows  you 
to  step  through  a  program  one  line  at  a  time.  This  command  is  primarily  a 
debugging  tool. 

Syntax 

SET  STEP  on/OFF 

Defaults 

The  default  for  SET  STEP  is  OFF. 

Usage 

During  operations  with  SET  STEP  ON,  a  single  program  instruction  is  executed 
at  a  time.  The  result  of  each  operation  is  displayed.  Before  the  next  instruction 
is  executed,  the  following  message  appears: 

Press  SPACE  to  Step,  S  to  Suspend,  or  Esc  to  Cancel... 

Program  processing  pauses  until  you  enter  one  of  the  choices. 


See  Also 

COMPILE,  DEBUG,  DO,  SET  DEBUG,  SET  DEVELOPMENT,  SET  ECHO, 
SET  TALK 
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SET  TALK 


SET  TALK  determines  whether  the  response  to  certain  dBASE  IV  commands  is 
displayed. 

Syntax 

SET  TALK  ON/off 

Default 

The  default  for  SET  TALK  is  ON. 

Usage 

SET  TALK  is  usually  ON  during  interactive  use.  It  displays  the  following  infor¬ 
mation  as  each  record  or  command  is  processed:  record  numbers,  memory 
variables,  and  the  results  of  commands  such  as  APPEND  FROM,  COPY,  PACK, 
STORE,  and  SUM. 

SET  TALK  OFF  is  used  in  programs  to  control  what  appears  on  the  screen  and 
on  the  printer. 


Example 

After  you  SET  TALK  OFF,  a  command  response  is  not  displayed. 

%urr=1ZX5 
vw.1Z545.0D 
Vi\SET  TAX  OFF 
nf&thar  -  Heller 


See  Also 

SET  DEBUG,  SET  ECHO,  SET  STEP 
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SET  TITLE 


SET  TITLE  turns  the  catalog  file  title  prompt  on  and  off. 

Syntax 

SET  TITLE  ON/off 

Default 

The  default  for  SET  TITLE  is  ON. 


Usage 

When  SET  CATALOG  is  ON,  files  are  automatically  added  to  the  catalog  when¬ 
ever  they  are  created,  used,  or  saved.  If  SET  TITLE  is  ON,  you  are  prompted  for 
a  catalog  file  title  at  this  time,  provided  the  file  isn’t  already  in  the  catalog.  With 
SET  TITLE  OFF,  this  prompt  does  not  appear. 

In  Report  Design,  Label  Design,  Database  Design,  Query  Design,  Form 
Design,  Program  Design,  and  Application  Design,  you  can  add  or  modify  the 
title  (also  called  the  Description),  using  the  pull-down  menus. 

For  other  commands,  to  add  a  title  to  a  file’s  catalog  record,  you  must  use  com¬ 
mands  such  as  EDIT  or  REPLACE  to  modify  the  title  field  in  the  catalog  file 
open  in  work  area  10.  You  can  open  and  modify  a  catalog  file  in  any  work  area; 
10  is  the  work  area  that  is  opened  with  SET  CATALOG. 


See  Also 

EDIT,  REPLACE,  SET  CATALOG 
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SET  TRAP 


SET  TRAP  activates  the  debugger  when  an  error  occurs  in  a  program . 

Syntax 

SET  TRAP  on/OFF 

Default 

The  default  for  SET  TRAP  is  OFF. 


Usage 

When  SET  TRAP  is  ON,  the  debugger  is  called  when  an  error  occurs,  or  if  you 
press  the  Esc  key.  The  program  is  halted  at  the  line  where  the  error  has 
occurred.  If  ON  ERROR  is  in  effect,  it  takes  precedence  over  SET  TRAP  and 
the  ON  ERROR  statement  controls  the  program. 

When  SET  TRAP  is  OFF,  and  no  ON  ERROR  condition  is  specified,  then  error 
conditions  give  you  three  options: 

■  Cancel  the  program 

■  Ignore  the  error 

■  Suspend  the  program 

If  SET  TRAP  is  ON,  dBASE  IV  calls  the  debugger.  The  functions  that  SET  TRAP 
performed  in  dBASE  III  PLUS  are  performed  by  SET  DEVELOPMENT  in 
dBASE  IV. 


See  Also 

DEBUG,  ON  ERROR,  SET  DEBUG,  SET  DEVELOPMENT 
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SET  TYPEAHEAD 


SET  TYPEAHEAD  specifies  the  size  of  the  type-ahead  buffer. 


Syntax 

SET  TYPEAHEAD  TO  <  cxpN  > 

Defaults 

The  default  number  of  characters  that  the  type-ahead  buffer  holds  is  20.  The 
allowable  range  is  an  integer  between  0  and  32,000. 


Usage 

Fast  typists  can  use  this  command  to  increase  the  capacity  of  the  type-ahead 
buffer  so  that  they  do  not  get  ahead  of  the  program  and  lose  keystrokes.  SET 
TYPEAHEAD  works  only  when  SET  ESCAPE  is  ON. 

In  full-screen  EDIT  or  APPEND  operations,  the  type-ahead  buffer  will  hold  only 
20  characters  regardless  of  a  previous  setting  with  SET  TYPEAHEAD  TO. 


Tips 

If  you  execute  an  error-handling  program  using  ON  ERROR  DO  <  program  >  , 
it  is  a  good  idea  to  completely  disable  the  type-ahead  buffer.  Include  SET 
TYPEAHEAD  TO  0  as  the  first  line  of  this  program.  This  deactivates  both  the 
ON  KEY  command  and  the  INKEY()  function.  Because  an  error  is  an  unantici¬ 
pated  condition,  disabling  the  type-ahead  buffer  is  a  safety  precaution. 


Special  Cases 

If  you  try  to  enter  more  than  the  specified  number  of  characters  into  the  type- 
ahead  buffer,  all  the  extra  characters  are  lost.  If  SET  BELL  is  ON,  the  beep  will 
sound.  If  this  happens  repeatedly,  you  should  increase  the  size  of  the  type-ahead 
buffer. 


See  Also 

INKEYQ,  ON,  SET  BELL,  SET  ESCAPE 
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SET  UNIQUE 


SET  UNIQUE  determines  whether  all  records  with  the  same  key  value  are 
included  in  the  index  (.ndx)  or  the  multiple  index  (.mdx)  file. 


Syntax 

SET  UNIQUE  on/OFF 

Defaults 

The  default  for  SET  UNIQUE  is  OFF. 


Usage 

If  you  create  a  new  index  file  while  SET  UNIQUE  is  ON,  and  several  records 
have  the  same  key  value,  only  the  first  record  that  dBASE  IV  encounters  with 
that  value  is  included  in  the  new  index  file. 

Whenever  you  REINDEX  an  index  file  that  was  created  with  UNIQUE,  the  file 
retains  its  UNIQUE  status,  regardless  of  whether  SET  UNIQUE  is  ON  or  OFF. 

Adding  new  records  or  editing  existing  records  in  the  database  file  when  a 
unique  index  is  open  does  not  change  the  unique  status  of  the  index  file.  This 
means  that  if  you  APPEND  a  record  that  contains  an  index  key  that  is  already  in 
the  index  file,  that  record  does  not  become  a  part  of  the  index  file,  although  it 
gets  added  to  the  database  file. 

Similarly,  EDITing  a  record  and  changing  its  key  to  one  which  is  already  in  the 
unique  index  file  removes  that  record  from  the  index  file. 


Programming  Note 

To  restore  an  index  file  to  a  non-unique  status,  rebuild  the  index  with  SET 
UNIQUE  OFF  and  the  INDEX  ON  command. 
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SET  UNIQUE 


Examples 

To  LIST  all  of  the  Part_names  in  the  Items  database  file  without  repeating  a 
part: 


.  LSE  Items 
.  SET  LNIGLE  CM 

.  IWEX  CN  fart-name  TO  Itermame 

1CHK  indexed  10  Records  indexed 

.  LIST  farUname 

Record U  Part_name 

12  HXX  CASE 

4  (HAIR,  DESK 

11  CHAIR/  SIDE 

15  DE9 </  EXECUTIVE  5-TOOT 

8  FILE  C^ET,  2  DRAWER 

9  FILE  OSBIfET,  4  DRAWER 

7  LAW3,  FLOOR 

1  SOFA/  6-F00T 

3  SOFA,  8-FCOT 

6  TAELE,  QD 


See  Also 

FIND,  INDEX,  REINDEX,  SEEK,  SEEK(),  SET  INDEX,  SET  ORDER,  USE 
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SET  VIEW 


SET  VIEW  performs  a  query  (.qbo  or  qbe)  created  in  the  Control  Center  or 
from  the  dot  prompt,  or  updates  the  environment  contained  in  a 
dBASE  III  PLUS  view  (.vue)  file. 


Syntax 

SET  VIEW  TO  <  query  filename  >  /<  view  filename  >  /? 


Usage 

This  command  performs  a  dBASE  IV  query  defined  in  a  .qbo  or  .qbe  file.  The 
query  may  have  been  created  by  calling  the  query  designer  from  the  Control 
Center,  or  with  CREATE/ MODIFY  QUERY  or  CREATE/ MODIFY  VIEW 

You  may  either  enter  a  view  filename  as  part  of  the  syntax,  or  use  the  catalog 
query  clause,  ?,  to  open  a  menu  of  all  .qbo,  .qbe,  and  .vue  files  in  the  open 
catalog. 

SET  VIEW  TO  updates  a  catalog  if  one  is  open  and  SET  CATALOG  is  ON.  If  a 
catalog  is  in  use  and  SET  CATALOG  is  ON,  each  file  opened  will  be  added  to  the 
catalog  unless  it  is  already  there,  and  you  will  be  prompted  for  a  title  if  SET 
TITLE  is  ON. 

File  Search  Order 

If  you  do  not  provide  a  file  extension  with  SET  VIEW,  dBASE  IV  searches  for  a 
compiled  query  file  with  a  .qbo  extension.  If  it  finds  a  .qbo,  it  executes  that  file. 

If  dBASE  IV  cannot  locate  a  .qbo  file  in  the  currently  defined  paths,  it  looks  for 
a  .qbe  file;  that  is,  a  query  program  file  that  has  not  been  compiled.  If  it  finds  a 
.qbe  file,  dBASE  IV  compiles  it  to  a  .qbo  and  executes  it 

If  dBASE  IV  finds  neither  a  .qbe  file,  nor  a  .qbo  file,  then  it  looks  for  a 
dBASE  III  PLUS  view  (.vue)  file.  The  .vue  file  is  loaded  into  the  qbe  form,  and 
update  files  with  .upd  and  .upo  extensions  are  generated  from  the 
dBASE  III  PLUS  .vue  file. 

To  execute  view  files  that  are  updated  from  dBASE  III  PLUS  .vue  files  to  .upd 
or  .upo  files,  you  must  use  the  DO  command.  SET  VIEW  will  not  find  or  exe¬ 
cute  them.  For  example: 

.  DO  VfiLe.ipd 

dBASE  IV  view  (.qbo  or  qbe)  files  cannot  be  used  in  dBASE  III  PLUS. 
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SET  VIEW 


dBASE  IV  View  Files 

AdBASE  IV  view  consists  of: 

■  All  open  database  files,  index  files,  and  the  work  area  number  of  each 

■  All  relations  between  the  database  files 

■  The  currently  selected  work  area  number 

■  The  active  field  list 

■  The  active  filter 

■  The  open  format  (.fmt)  file,  if  any 

See  Also 

CREATE/ MODIFY  VIEW/ QUERY,  SET  CATALOG,  SET  HELDS,  SET  HLTER, 
SET  FORMAT,  SET  INDEX,  SET  ORDER,  SET  RELATION,  SET  TITLE 
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SET  WINDOW 


S£T  */-//v<9o  VI/ 


This  command-sets  a  default  window  that  allows  you  to  edit  a  memo  field 
within^this  default  window  while  you  are  in  EDIT  or  BROWSE. 

Syntax 

SET  WINDOW  OF  MEMO  TO  <  window  name> 

The  <  window  name>  is  the  name  of  a  previously  DEFINEd  window. 

Usage 

This  command  allows  you  to  use  a  special  window  to  edit  memo  fields  while 
you  are  using  full-screen  commands  such  as  EDIT,  APPEND,  BROWSE, 
CHANGE,  and  READ. 

The  WINDOW  clause  that  you  specify  with  the  @...GET  command  for  editing 
memo  fields  overrides  the  window  specified  by  the  SET  WINDOW  command. 

Examples 

The  first  and  the  third  @...GET  commands  use  the  full-screen  default  window 
to  edit  memo  fields.  The  second  @...GET  uses  the  window  specified  with  the 
SET  WINDOW  OF  MEMO  command. 

U3ECU  XhN  FROM  5^5  TO  15^0 
wr  FROM  1^30  TO  11,7V 
E*7  TO  JCFN 


2.1  GET  TEK2 tOMJOU  XM 

3.1  GET  FEKB 


If  you  try  to  SET  WINDOW  OF  MEMO  TO  to  an  undefined  window  name,  the 
error  message  Window  has  not  been  denned  appears. 

See  Also 

ACTIVATE  SCREEN,  ACTIVATE  WINDOW,  CLEAR  WINDOwTdEFINE 
WINDOW,  MOVE  WINDOW  *— 
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Functions 


& 

&  is  the  macro  substitution  function.  It  substitutes  the  contents  of  a  memory 
variable  for  a  literal  variable  name  where  dBASE  IV  would  take  the  literal  vari¬ 
able  name.  This  function  can  be  used  only  for  character  variables. 

Syntax 

&  <  character  variable  >  [.]  [<  cstring>  ] 

Usage 

This  function  is  used  to  obtain  the  contents  of  a  character  memory  variable 
when  dBASE  IV  expects  a  literal  value  rather  than  a  character  expression. 

Some  examples  of  when  dBASE  IV  expects  a  literal  value  are  FIND,  USE,  and 
other  commands  that  use  a  filename. 

Use  the  period  (.)  as  the  optional  macro  terminator.  A  macro  terminator 
ensures  the  integrity  of  the  command  and  clearly  delimits  the  end  of  the  macro 
in  a  character  string. 

Examples 

Use  the  FIND  command  with  a  memory  variable: 

.  fihame  =  "fitters' 

Peters 

.  USE  Customer  HOEX  CLs-name 
.  FIW&tTame. 

.  ?  PEQDO,  Lastneme 
4  Peters 
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& 


Substitute  a  memory  variable  for  a  database  file  filename,  then  USE  the  vari¬ 
able  instead  of  the  filename: 


.  ACCEPT  'Biter  the  cbtatsse  file  directory:  ’  TO  ^directory 
Enter  the  database  file  directory:  \cBASE 
.  ACCEPT  'Biter  a  database  filename:  '  TO  filename 
Enter  a  cbtabase  filename:  Invoices 
.  USE  C:8tiirectory.  \& filename . 

.  ?  CBFO 

C:\DBNSE\IMOICES.DBF 
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The  ABS()  function  returns  the  absolute  value  of  a  numeric  expression  without 
regard  to  its  sign. 


Syntax 

ABS(  <  expN  >  ) 


Usage 


Use  this  function  to  find  the  absolute  value  of  a  numeric  expression.  The  abso¬ 
lute  value  of  both  +  3  and  —  3  equals  3.  This  function  enables  you  to  find  the 
difference  between  two  numbers  without  regard  to  their  sign. 

The  response  is  always  a  positive  number. 


Example 


To  determine  the  number  of  days  between  two  dates: 


.  dstel  =  {1Z2SM& 

.  dateZ  =  WV01/8& 
04/01  /ffi 

.  ?  ABSCcbtel  -  dateZ) 
268.00 

.  ?  JBSCdateZ  -  dstel) 
268.00 
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ACCESS() 


The  ACCESS()  function  returns  the  access  level  of  the  current  user. 


Syntax 

ACCESS() 

Usage 

The  ACCESS()  function  allows  you  to  build  security  into  a  network  application 
program.  The  access  level  returned  by  this  function  can  be  used  to  test  privi¬ 
leges  assigned  with  PROTECT. 


Programming  Notes 

Use  this  function  to  change  access  levels.  For  example: 
IF  ACCESSO  <  3 


can  easily  be  changed  to: 

IF  ACCESSO  <  8 

To  prevent  a  user  from  modifying  his  or  her  access  level,  use  a  compiled  pro¬ 
gram  that  checks  the  ACCESS()  level.  Remove  the  source  file  (  prg)  from  the 
user’s  access  level.  The  compiled  program  files  cannot  be  modified  by  the  user. 

The  following  program  exampls  tests  the  user’s  access  level.  If  the  access  level 
is  less  than  3,  it  runs  a  sub-program.  If  higher  than  3,  it  sounds  the  beep  and 
displays  the  ACCESS  NOT  ALLOWED  message. 

ACCEPT  "  Biter  choice  *  TO  Choice 
DO  CASE 

CASE  Choice**  1" 

IF  ACCESSO  <  3 
DO  Program 
ELSE 
?  ORC7) 

?  "access  not  Aujaer 

WAIT 

RETLFN  TO  MASTER 
BDIF 

CASE  Choice*'? 


BDCASE 
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Special  Cases 

If  dBASE  IV  does  not  find  the  Dbsystem.db  file  during  startup,  it  does  not 
present  the  log-in  screen  to  the  user.  ACCESSQ  returns  a  zero  if  the  user  has 
not  entered  dBASE  IV  through  the  log-in  screen.  A  user  with  an  access  level  of 
zero  cannot  access  encrypted  files.  To  prevent  ACCESSQ  from  returning  a  zero, 
it  is  recommended  that  you  keep  the  Dbsystem.db  file  in  the  same  directory  as 
dBASE  IV,  and  always  enter  through  the  log-in  screen. 

If  you  write  programs  that  use  encrypted  files,  check  the  user’s  access  level 
early  in  the  program.  If  ACCESSQ  returns  a  zero,  your  program  might  prompt 
the  user  to  log  in  again,  or  to  contact  the  Network  Administrator  for  assistance. 

In  a  single-user  environment,  ACCESSQ  always  returns  a  zero. 


See  Also 

FLOCKQ,  PROTECT,  RLOCKQ,  UNLOCKQ,  USERQ 
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ACOS() 


The  ACOS()  arccosine  function  calculates  and  returns  the  angle  size  in  radians 
for  any  given  cosine  value. 

Syntax 

ACOS(  <  expN  >  ) 


Usage 

The  variable  (<  expN  >  )  is  a  numeric  expression  that  is  the  cosine  of  a  particu¬ 
lar  angle.  The  value  of  the  numeric  expression  must  be  between  —  1.0  and 
+  1.0  inclusive. 

The  response  is  always  a  number  that  represents  an  angle  size  in  radians 
between  zero  and  n.  The  SET  DECIMALS  and  SET  PRECISION  commands 
determine  the  number  of  decimal  points  and  the  accuracy  displayed. 


Example 

To  assign  the  angle  in  radians  represented  by  a  cosine  value,  determined  in  a 
four-level  substitution,  to  a  memory  variable: 

.  SET  DECIMALS  TO  4 
.  x=  8.4852 

8.482 

°  y  =  12 

12.0000 

.  Moos  =x  / y 

o.t un 

.  angle  =  ACOSCMcos) 

0.7854 


See  Also 

ASIN(),  AEANQ,  ATN2(),  COS(),  DTOR(),  FIXED(),  FLOAT(),  PI(),  RTODQ, 
SET  DECIMALS,  SET  PRECISION,  SIN(),  TAN() 
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ALIAS() 


The  AL1AS()  function  returns  the  alias  name  of  a  specified  work  area.  It  returns 
the  name  of  the  current  work  area  if  you  do  not  specify  a  work  area. 


Syntax 

AUAS([<  expN  >  ]) 


Usage 

dBASE  IV  allows  you  to  open  the  same  database  file  in  nine  different  work 
areas,  provided  you  specify  a  unique  alias  each  time  you  USE  the  same  data¬ 
base. 

The  ALIAS()  function  returns  the  filename  or  unique  alias  associated  with  any 
work  area.  The  optional  variable  <  expN >  specifies  which  work  area  to  check 
and  is  any  valid  numeric  expression  between  1  and  10.  If  you  do  not  specify  a 
work  area  the  current  work  area  is  assumed. 

If  you  use  a  decimal  number  such  as  7.5  for  <  expN>  ,  it  is  truncated  to  7. 


Example 

This  example  shows  a  program  module  which  executes  if  the  work  area  speci¬ 
fied  is  a  value  between  1  and  10.  If  the  work  area  number  is  greater  than  10, 
this  program  sounds  the  beep,  displays  a  message  asking  you  to  close  an  open 
database,  and  returns  control  to  the  master  program  that  called  it. 

ACCEPT  "Biter  a  database  filename:  ’  TO  filename 
workarea  =  1 

DO  WILE  "  «  ALIAS  (workarea)  .AM),  workarea  <=  10 
workarea  =  workarea  1 
BOOO 

IF  work  area  =  11 
?  OR  (7) 

??  "ft*t  close  an  open  database  file  first." 

RETUN  TO  MUSTER 
BDIF 

SafCT  work  area 
USE  &filename. 
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The  ASC()  function  returns  the  ASCII  decimal  code  of  a  string’s  first  character. 

Appendix  H  lists  the  decimal  ASCII  values  for  the  IBM  character  set  0  through 
255.  Please  refer  to  this  appendix  to  identify  a  decimal  value  returned  by  this 
function. 

Syntax 

ASC  (<  expC>  ) 

Examples 

.  ?  ASCC Nest LeT) 

78.00 

.  STORE  "127  TO  ruiber 
123.00 
.  ?  ASCCnrter) 

49.CD 
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The  ASIN()  arcsine  function  calculates  and  returns  the  angle  size  in  radians  for 
any  given  sine  value. 


Syntax 

ASIN(  <  expN  >  ) 


Usage 

The  variable  (<  expN  >  )  is  a  numeric  expression  that  is  the  sine  of  a  particular 
angle.  The  value  of  the  numeric  expression  must  be  between  —  1.0  and  +  1.0 
inclusive. 

The  response  is  always  a  floating  point  number  that  represents  an  angle  size  in 
radians  between  —  n/2  and  +  n/2.  The  SET  DECIMALS  and  SET  PRECISION 
commands  determine  the  number  of  decimal  points  and  the  accuracy 
displayed. 


Examples 

To  find  the  angle  in  radians  represented  by  a  sine  value: 


.  ?  ASINC.Sm 

.5236 


To  assign  the  sine  value  to  an  expression: 


.  star  -  .5000 

0.5000 

.  X  =  ASIN(star) 

0.5236 


See  Also 

ACOS(),  AEAN(),  ATN2(),  COS(),  DTOR(),  RTOD(),  SET  DECIMALS, 
SET  PRECISION,  SIN(),  TAN() 
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The  AT()  function  returns  a  number  that  shows  the  starting  position  of  a  char¬ 
acter  string  within  a  second  string.  The  contained  character  string  is  called  a 
substring.  If  the  substring  is  not  contained  within  the  second  expression,  the 
function  returns  a  zero. 


Syntax 

AT(<  expC>  ,<  expC>  /memvar) 


Example 

Using  the  Customer  database  Hie,  check  the  Lastname  field  for  the  name 
"Wright* : 

.  USE  Customer 

.  ?  ATCUricfif,  Lastname)  <  >  0 
.T. 

9QP 

CUSTOMER:  Record  to  2 
.  ? ATCUricfif,  Lastname)  <>0 


See  Also 

LEFTQ,  RIGHTO,  SUBSTR() 
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ATANQ 


The  ATANQ  arctangent  function  calculates  and  returns  the  angle  size  in  radians 
for  any  given  tangent  value. 


Syntax 

ATAN(<  expN  >  ) 


Usage 

The  variable  (<  expN  >  )  is  a  numeric  expression  that  is  the  tangent  of  a  partic¬ 
ular  angle.  The  range  is  between  +  n/2  and  —  n/2. 

The  response  is  always  a  number  that  represents  an  angle  size  in  radians.  The 
SET  DECIMALS  and  SET  PRECISION  commands  determine  the  number  of  dec¬ 
imal  points  and  the  accuracy  displayed. 


Examples 

To  find  the  angle  in  radians  represented  by  a  tangent  value: 

.  ?  AT/NCI. COO) 

0.7854 

To  assign  the  tangent  value  to  an  expression: 

.  Star  *  1.000 
.  mar  *  ATJNCstar) 

0.7854 


See  Also 

ACOSQ,  ASIN(),  ATN2Q,  COSO,  DTOR(),  RTODQ,  SET  DECIMALS, 
SET  PRECISION,  SINQ,  TANQ 
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The  ATN2()  arctangent  function  calculates  and  returns  the  angle  size  in  radians 
when  the  cosine  and  sine  of  a  given  point  are  specified. 


Syntax 

ATN2(<  expNl>  ,<  expN2>  ) 


<  expNl  >  is  the  sine  of  a  particular  angle,  and  ( <  expN2  >  )  is  the  cosine  of 
that  same  angle.  The  value  of  the  expression  <  expNl  >  /  <  expN2  >  must  fall 
within  the  range  of  +  n  and  —  n. 


Usage 


This  function  returns  values  in  all  four  quadrants,  and  is  equivalent  to 
ATAN(x/y).  It  is  easier  to  use  than  ATAN(x/y)  because  it  eliminates  divide  by 
zero  errors. 

The  response  is  always  a  number  that  represents  an  angle  size  in  radians 
between  +  n  and  —  n.  The  SET  DECIMALS  command  determines  the  accuracy 
of  the  display. 

Example 

This  example  shows  an  integrated  usage  of  trigonometric  functions.  You  get  the 
sine  and  cosine  of  30  degrees  with  the  degrees  to  radians  conversion  function 
DTOR(),  while  concurrently  saving  those  values  to  the  memory  variables  x  and 
y.  Next,  you  use  the  ATN2()  function  inside  the  radians  to  degrees  conversion 
function  RTOD()  to  get  the  degrees  that  correspond  to  this  sine  cosine  pair. 

The  reason  for  using  the  memory  variables  is  to  take  advantage  of  the  20-place 
internal  numeric  accuracy  of  dBASE  IV  without  typing  large  numeric  values  or 
changing  the  decimals  setting. 

.  x=Sm(DKFCJD) 

.50 

.  y=CDS(DWROO)) 

.85 

.  ?  RTWCA  Tt2(x,y)) 

30.00 

See  Also 

AEAN(),  COS(),  DTOR(),  RTOD( ),  SET  DECIMALS,  SIN(),  TAN() 
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BAR() 


The  BAR()  function  returns  the  BAR  number  of  the  most  recently  selected  BAR 
from  a  pop-up  menu. 


Syntax 

8AR() 


Usage 


Use  this  function  to  get  the  BAR  number  of  the  last  selected  BAR  from  the  cur¬ 
rently  active  pop-up  menu. 

The  BAR()  function  returns  a  zero  if:' 

■  There  is  no  active  pop-up  menu 

■  No  pop-up  menu  has  been  defined 

■  The  Esc  key  was  pressed  to  DEACTIVATE  the  active  pop-up  menu 

The  BAR()  function  returns  the  BAR  number  (such  as  1,  2)  if  the  pop-up  menu 
was  defined  using  the  DEFINE  BAR  command. 

The  BAR()  function  returns  the  line  number  for  the  prompt,  counting  the  first 
line  within  the  pop-up  screen  area  as  1,  if  the  pop-up  prompts  were  defined 
using  the  DEFINE  POPUP  command. 
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BAR() 


Example 

Select  a  field  from  a  file  structure  menu  and  list  it. 


c  USE  Client 

.  DEFINE  PCRJP  cUields  FPCM  10 JO  TO  2D  JO  PRCfPT  STRJCTVRE 
■  CNJgjpiCN  FCRP  cLfields (rXCTlVATEPCFlP  cU^ldT) 

*  ^^ixxe  Lastname  from  ~the  menu. 

.  ?*BMO 

3.00 

.  fldjtoicc  =  FIELD  (BflPO) 

LASTWe 

(  ) 

.  DISPLAY  Ml  SfldphDice. 

Record#  LASTNAfC  *==- 

1  Wriest 

2  Bailey 

3  Martinez 

4  Peters 

5  YanBda 

6  Tiimcns 

7  Beluga 

8  Beckinrt 


See  Also 

ACTIVATE  POPUP,  DEFINE  POPUP,  POPUP(),  PROMPT() 
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BOF() 


The  BOF()  function  indicates  the  beginning  of  the  file.  This  function  is 
intended  for  programming  applications  in  which  the  database  is  read  in  reverse 
order.  A  logical  true  (.T.)  is  returned  when  an  attempt  is  made  to  move  the 
record  pointer  before  the  first  logical  record  of  the  specified  file. 

Syntax 

BOF([<  alias  >  J) 

Special  Case 

If  no  database  is  in  USE,  BOF()  returns  a  logical  false  (.F.). 

Example 

In  a  procedure  that  edits  records  and  moves  the  record  pointer  according  to 
the  exit  key  value,  use  BOF()  as  a  test  to  avoid  moving  the  record  pointer  to  a 
nonexistent  record. 

DO  WHILE  .T. 

EDIT  NEXT  1 


DO  CASE 

CASE  STR(REAOKEY(  ),3>  S  "  6,  7£Z 


*  QftMa  key  was  pressed. 

30 P  A 

*  O°o  not  try  to  EDIT  records  before  0OFC  ). 
IF  BOFO 


GO  TCP 
BJDIF 


BDCASE 


See  Also 


EOF() 
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CALL() 


The  CALL()  function  is  used  in  programming  to  execute  binary  program 
modules. 


Syntax 

CALL(<  filename  >  ,<  expC>  /<  memvar>  ) 

Usage 

This  function  is  used  with  the  LOAD  command  to  execute  binary  programs 
written  in  other  languages  (such  as  assembly  or  C)  within  dBASE  IV  programs. 
First,  load  a  subroutine,  then  execute  it  using  the  CALL()  function.  You  can 
then  use  any  value  returned  by  the  function  in  a  dBASE  IV  expression. 

When  the  function  is  executed,  the  address  of  the  argument  is  loaded  into  the 
data  segment  (DS)  and  BX  register.  Program  control  is  transferred  to  the  begin* 
ning  of  the  specified  loaded  module  for  execution. 

Memory  variables  and  array  elements  may  be  passed  to  the  binary  program 
module.  To  pass  memory  variables  to  the  CALL()  function,  you  must  first  define 
them.  To  use  arrays  with  CALL(),  you  must  declare  them  and  reference  their 
element  coordinates. 


Example 

This  program  example  LOADs  the  binary  file  into  memory.  Next,  the  array 
Mdrives  is  DECLAREd.  The  first  element  of  Mdrives  is  assigned  a  single  space, 
the  remaining  nine  elements  a*e  null.  The  first  print  statement  (?)  prints  a  mes¬ 
sage  for  the  user  about  default  drive  status,  and  assigns  the  default  drive  to  the 
first  element  of  Mdrives.  The  second  print  statement  verifies  that  the  first  ele¬ 
ment  of  Mdrives  is,  in  fact  C. 

S' 

o  LOAD  Getdrive 
.  DECLARE  fttivesCIOJ 
.  MJriiesCIJ  =  "  ’ 

.  ?  "The  arrant  cHva  if,  CALLCGetdriyeTJ&ivasCV) 

|  The  curwit  drive  is  C 
.?  MJriiesEIJ 
C 

See  Also 

DECLARE,  LOAD,  STORE 
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CDOW() 


The  CDOW()  function  returns  the  name  of  the  day  of  the  week  from  a  date 
expression. 

Syntax 

CDOW(<  expD>  ) 


Usage 

The  date  expression  is  a  memory  variable,  a  field,  or  any  function  that  returns 
date  type  data. 


Examples 

.  ?  CDCU«n2/29/88D 
Nxriay 

To  determine  if  the  current  date  is  a  weekday  or  a  weekend: 

.  ?  ' Today  is  '  +  IIF(CDCU(MJEO)  =  'S’,  'an  a  ueekerd. ',  ' a  ueekday.') 
Today  is  a  weekday. 

See  Also 

CTOD(),  DATE(),  DAY(),  DOW(),  DTOC() 
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CEILING() 


The  CEILING()  function  calculates  and  returns  the  smallest  integer  that  is 
greater  than  or  equal  to  the  value  specified  in  the  numeric  expression. 


Syntax 

CEILIN<3<<  expN  >  ) 

Usage 

Use  this  function  to  find  the  smallest  integer  that  is  greater  than  or  equal  to  a 
given  value.  The  value  returned  is  the  same  data  type  as  the  numeric  variable 
<  expN >  specified. 


Examples 

.  first  =  125 
1Z3.00 

*  second  =  10 

10.00 

.  ?  CEIUNSCfirst  /  second) 
13.00 


CEILING(),  unlike  ROUNDQ,  always  returns  an  integer  closer  to  zero. 


.  ?  CHUNS  (-5. 556) 

-5.00 

.  ?  F€LtD(-5. 556/D 
-6.0D 


See  Also 

FLOORQ,  ROUNDQ 
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CHANGEQ 


The  CHANGEQ  function  determines  if  a  record  has  been  changed  since  it  was 
opened  in  a  multi-user  environment. 

Syntax 

CHANGEQ 

Usage 

This  function  is  valid  only  for  records  that  have  been  updated  with  the  CON¬ 
VERT  command. 

{{Alternative  1:  The  CONVERT  command  adds  a  field  called  _DBASELOCK  to 
the  structure  of  the  active  database  file  and  keeps  track  of  "Count”  which  is  a 
two-digit  hexadecimal  number  that  the  CHANGEQ  function  reads.}} 

{{Alternative  2:  The  CONVERT  command  creates  a  new  file  with  the  extension 
.cvt.  This  file  contains  the  field  _DBASELOCK.  The  network  user  must  put  this 
.cvt  file  into  USE  for  the  CHANGEQ  function  to  work.}} 

The  CHANGEQ  function  checks  the  count  for  the  fields  in  the  current  record  to 
see  if  the  count  has  been  updated  since  the  record  was  opened.  It  returns  a  log¬ 
ical  true  (.T.)  if  the  count  value  of  the  current  record  differs  from  the  value 
stored  in  the  header  of  the  record. 


It  returns  a  logical  false  (.F.)  if  the  values  are  the  same. 


ately  updated.  If  you  use  the  CHANGE()  function  at  this  point,  it  will 
return  a  true.  However,  if  the  transaction  is  not  completed  and  a  roll¬ 
back  occurs,  you  will  not  know  that  the  change  to  the  record  is  no 
longer  valid. 

See  Also 

CONVERT,  FLOCKQ,  LKSYSQ,  RLOCKQ,  SET  REFRESH 


NOTE 

This  /unction  is  not  totally  reliable  if  used  during  transaction  processing. 
When  a  record  is  updated  in  a  transaction,  its  record  count  is  immedi¬ 
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The  CHR()  function  converts  a  number  to  a  character. 

Syntax 

CHR(  <  expN  >  ) 


This  function  enables  you  to  send  any  value  from  the  IBM  extended  character 
set  to  a  printer  or  the  screen.  <  expN>  must  be  an  integer  from  1  to  255. 

Note  that  not  all  printers  support  the  IBM  extended  character  set.  Check  the 
ASCII  code  table  for  your  printer  if  a  character  from  the  extended  set  that  you 
can  display  will  not  print. 

You  can  also  use  CHR()  to  send  control  codes  to  the  printer. 

Examples 

To  display  capital  A  which  is  equal  to  ASCII  decimal  65: 

„  ?  Off  (65) 

A 

Use  ASCII  decimal  7  to  sound  the  bell  and  display  a  screen  message: 

.  ?  (}G(7)-r9e  nore  careful' 

Be  more  careful 

When  you  use  CHR()  in  comparisons,  CHR(O)  must  be  on  the  left  side  of  the 
equation.  When  dBASE  IV  performs  character  string  comparisons,  it  reads 
what  is  on  the  right  side  first.  Because  CHR(O)  is  a  null  string,  if  it  is  on  the 
right  side,  dBASE  IV  reads  no  further  and  returns  a  true  (.T.). 

.  mem  =  'abf 
abc 

.  ?  mem  =  ChFCD) 

.T. 

.  ?  ORCCD  =  men 

.F. 


See  Also 
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CMONTHQ 


The  CMONTH()  function  returns  the  name  of  the  month  from  a  date 
expression. 


Syntax 

CMONTH(<  expD>  ) 


Usage 

The  date  expression  is  a  memory  variable,  a  field,  or  any  function  that  returns 
date  type  data. 


Examples 

If  the  system  date  is  05/15/88: 

.  ?  CKNTH(DATEO) 

To  determine  which  month  is  76  days  from  the  current  date,  first  store  the 
name  of  the  month  to  a  memory  variable: 

.  "tenth  =  CKNTHCDATEO+76) 

July 

.  ?  ’He  krill  visit  ycu  in  0  *  Hicnth 
We  will  visit  you  in  July 

See  Also 

DATEQ,  MONTHQ 
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COL() 


The  COL()  function  returns  the  current  column  position  of  the  cursor. 

Syntax 

COL<) 


The  COL()  function  may  be  used  for  relative  addressing.  Use  it  to  control  cur¬ 
sor  positioning  from  within  a  program.  Although  the  special  operator  $  can  also 
be  used  with  @...SAY  and  @...GET  commands  to  indicate  the  cursor  position 
on  the  display  or  the  printed  page,  COL()  can  do  it  easier  and  faster. 

For  example: 

@  1,  COL()  +  5  is  the  same  as  @  1,  $  +  5. 

Both  statements  move  the  screen  cursor  five  columns  to  the  right  of  the  cur¬ 
rent  position. 


Examples 

Use  COL()  within  a  program  to  find  the  current  cursor  position  on  the  screen. 
For  example,  if  you  want  to  end  a  loop  when  the  cursor  is  at  column  70,  part  of 
the  program  might  include: 

DO  VHILE  CCLCX  70 
S  5/CLO  +  5  SAY  'X1 
B€0O 


To  print  the  sentence  "This  is  relative  addressing"  starting  on  row  7,  column 
10: 


a  7,  10  SAY  "This  is  " 
a  7,  CCLO  SAY  "  relative  adfressincf 

See  Also 

@,  PCOLQ,  PROWQ,  ROW() 
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COMPLETED*) 


The  COMPLETED()  function  determines  whether  a  transaction  has  completed; 
that  is,  a  BEGIN  TRANSACTION  command  has  been  terminated  with  an 
END  TRANSACTION  command,  or  a  successful  ROLLBACK  has  occurred. 


Syntax 

COMPLETEDQ 


Usage 

Use  this  function  to  monitor  transaction  processing,  from  the  dot  prompt  or 
from  within  programs.  This  function  is  set  to  true  (.T.)  by  default.  When  you 
issue  a  BEGIN  TRANSACTION  command,  COMPLETED*)  is  changed  to  false 
(.F.).  When  you  issue  an  END  TRANSACTION  command,  it  is  reset  to  true  (.T.). 


Example 

To  test  for  the  successful  completion  of  a  transaction  in  a  program  file: 
ESIN  TTWNSACTICN 


BO  TRANSACTICN 
IF  .NJT.  OFLETEDO 
RCLLBMX 

IF  JOT.  RCLLBAOCO 
IF  ISWKEDO 
RESET 

BOIF 

?  "The  transaction  was  not  ccnpleted  and  could  not" 
?  "succesfully  be  restored." 

REUFN 

BOIF 

BOIF 


See  Also 

BEGIN  TRANSACTION/ END  TRANSACTION,  CHANGE*),  CONVERT,  LKSYSQ, 
ROLLBACK,  ROLLBACK*) 
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The  cosine  COS()  function  calculates  and  returns  the  cosine  value  for  any 
angle  size  in  radians. 


Syntax 

COS(<  expN  >  ) 


Usage 


The  variable  (<  expN  >  )  is  a  numeric  expression  that  is  the  size  of  an  angle 
measured  in  radians.  There  are  no  limits  on  this  numeric  expression. 

The  SET  DECIMALS  command  determines  the  number  of  decimal  points  and 
the  accuracy  of  the  display. 


Examples 

.  7C0SC7S5O 


CL7CJ71 


To  assign  the  cosine  value  to  a  memory  variable  expression: 


.  Mar  =./U/l 

0.7071 

.  Mcas  =  COSOnuer) 
0.76CE 


See  Also 

ACOSQ,  ASIN(),  ATANQ,  ATN2(),  DTOR(),  RTOD(),  SET  DECIMALS,  SIN(), 
TAN() 
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CTOD() 


The  CTOD()  function  converts  a  date  that  has  been  entered  or  stored  as  a  char¬ 
acter  string  to  a  date  type  variable. 

Syntax 

CTOD(  <  expC>  ) 


Defaults 

The  format  of  the  character  string  is  normally  mm/dd/yy,  but  this  format  can 
be  changed  by  SET  DATE  and  SET  CENTURY. 


Usage 

The  character  string  used  by  CTOD()  can  range  from  '01/01/0100*  to 
"12/31/9999".  A  twentieth  century  date  is  assumed  if  you  use  only  two  numbers 
for  the  year. 

You  can  also  use  {mm/dd/yy}  to  create  a  date  variable  from  a  literal  value. 


Examples 

You  can  use  CTOD  to  initialize  a  date  memory  variable  converting  a  blank  date 
string  ('//')  or  a  string  specifying  an  exact  date  (for  example,  '01/01/80'). 
You  could  then  use  the  date  variable,  for  example,  with  an  @...GET  command, 
to  enter  a  new  date  in  the  memory  variable  as  it  is  displayed  on  your  screen. 

.  STCRE  CTWC01/O1/ar)  TO  testdate 
01/01/80 
.  ?  testate 
01/01/8D 


To  convert  a  character  variable  to  a  date  variable: 


.  STCRE  ' 01AJ1/9J  TO  testdate 
01/01/83 

.  ?  TTFEC  testdate" ) 

C 

.  STCRE  CTCO(test±te)  TO  neu&te 
01/01/83 

.  ?  TYFECradateO 
D 
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CTOD() 


An  alternate  to  CTOD()  is  enclosing  the  date  argument  in  curly  braces: 

.  Leapcbte  =  <JJ2/29/8B> 

02/29/88 
.  SET  CENTUff  CN 
.  ?  Leapckte 
02/29/1988 


See  Also 

DATEQ,  DTOCQ,  DTOSQ,  SET  CENTURY,  SET  DATE 
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DATE() 


The  DATE()  function  returns  the  system  date  in  the  form  mm/dd/yy  unless  the 
format  has  been  changed  by  SET  CENTURY  or  SET  DATE. 

Syntax 

DATEQ 

Usage 

The  system  date  must  be  set  at  the  operating  system  level. 

Examples 

To  display  the  system  date: 

.  ?  CATEO 
04/01/88 

To  store  the  system  date  to  the  memory  variable  Mdate: 

.  STORE  CATEO  TO  Mate 
05/04/88 

or: 

.  Mate  =  DATED 
02/29/88 

See  Also 

SET  CENTURY,  SET  DATE 
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The  DAY()  function  returns  the  numeric  value  of  the  day  of  the  month  from  a 
date  expression. 


Syntax 

DAY(<  expD>  ) 


Usage 


The  date  expression  is  a  memory  variable,  a  Held,  or  any  function  that  returns 
date  type  data. 


Examples 

If  the  system  date  is  05/15/88: 

.  ?  MY  (DATE O) 

15 

To  store  the  day  from  the  system  date  to  the  memory  variable  Mday: 

.  STORE  DAYCDATEO)  TO  Ptby 
15.00 

.  ?  May 

15.00 

.  ?  TTFECMa/) 

N 

See  Also 

CDOWQ,  DATE(),  DOW() 
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DBF() 


The  DBF()  function  returns  the  name  of  the  database  file  in  USE  in  the 
currently  selected  work  area. 


Syntax 

DBF([<  alias  >  ]) 


Defaults 

If  no  database  file  is  open  in  the  specified  work  area,  DBF()  returns  a  null 
string. 


Usage 

This  function  is  useful  in  programming  to  enable  the  program  to  work  with  a 
file  that  is  in  USE  in  another  work  area. 


Examples 

To  determine  which  file  is  in  USE  when  you  are  in  the  interactive  mode: 

e  USE  Client 
.  ?  CBFO 
C:CLient.cfcf 


To  clear  all  the  work  areas,  but  retain  the  currently  selected  database  file  in  a 
program : 


filename  =  CBFO 
CLEAR  ALL 
USE  Sfilename. 


See  Also 

AUAS(),  FIELDQ,  KEY(),  MDX(),  NDX(),  TAG() 
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DELETED() 


The  DELETEDf;  fonction  Identifle*  recor da  that  ere  marked  for  deletion  A  logi 
cal  troe  ( 7  )  it  retorned  if  the  e»rrent  record  in  the  specified  work  area  »« 
marked  for  deletion,  if  it  i*  not,  a  logical  false  f  9  )  I e  retorned 


Syntax 

DELETEDff  <  allae^  J) 


Caaa 

ff  no  daraOsse  flic  <*  »n  fJ5£.  DELETED/ >  reform  P 


Example 

To  determine  if  the  correct  record  i«  marked  for  deletetion 

.  USE  Cltont 
.  ?  COS7EDO 
.9 . 

.  CEU7E 

1  ry//d  dn'emri. 

.  *  CELETELO 

X 


See  Also 

PACK  RECALL,  5ET  DELETED 
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puncnci* 


DIFFERENCE() 


The  DIFI'TKBNCE  (>  function  determines  the  difference  between  two 
SOUNDHXO  codes 

Syntax 

DIFFERENCE^  «xpC>  ,  <  e«pC>  ) 


Usage 

The  D1FFFKBNCE()  function  computes  the  difference  between  the  two  expres¬ 
sions  represented  by  <  expC>  and  returns  an  integer  between  0  and  4  TWo 
closely  matched  codes  return  a  difference  of  4,  and  two  codes  that  have  no  let¬ 
ters  in  common  return  a  code  of  1. 

The  two  expressions  evaluated  must  be  character  expressions.  Defined  variable 
names  mav  be  used. 


Example 

To  find  names  with  similar  SOUNDEXO  codes: 


.  tar  a  w* 

.  LIST  f'nitrwm 
Havorv#  Firatrwe* 

1  Fits*  l . 

2  Suits 

3  IHc 

4  Mstwrly 

5  Qaorgi  J . 

6  eerw 

7  YVxi 

S  Ri«xer 


Kiatvelee 

.  LIST  Ftrstwm  W  wim'  >2 

Firatrame 
4  Matsarly 

2  Salts 

.  LIST  Firttwm  K*  W*&B*TCrir9*ym*>  x  J 

HkkixV  F>r»tnaa» 

4  Ktafcarly 


Sm  Also 

SOUNDS  XO 
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DISKSPACE() 


The  DISKS  PACEQ  function  returns  an  integer  representing  the  number  of  bytes 
available  on  the  default  drive. 


Syntax 

DISKSPACEQ 


Programming  Note 

Use  DISKSPACEQ  with  RECCOUNTQ  and  RECSIZEQ  in  application  programs 
that  automatically  back  up  database  Hies.  This  function  lets  you  know  if  there 
is  sufficient  space  on  the  disk  for  the  backup  Hie.  See  the  example  under 
RECSIZEQ. 


Example 

SET  TALK  OFF 
USE  Client 

Mfilesize  =  (RECCCLNTO  *  RECSIZEO)  +  ZEO 
IF  DI9GPACEO  >  Mfilesize 
Copy  TO  A:Badop 

ELSE 

3  10,16  SAY  "There  is  rot  enou^i  rocnt  to  badap  the  file." 

eoiF 

SET  TALK  CN 


See  Also 

RECCOUNTQ,  RECSIZEQ 
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The  DMY()  function  converts  the  date  to  a  Day/Month/ Year  format  from  any 
valid  date  expression. 


Syntax 

DMY(<  expD>  ) 


This  function  converts  the  date  to  the  following  format: 

DD  Month  YY 

The  day  is  shown  without  a  leading  zero  as  one  or  two  digits.  The  month  is 
spelled  in  full,  and  the  year  is  shown  with  the  two  last  digits. 

If  SET  CENTURY  is  ON,  then  the  format  is: 

DD  Month  YYYY 

The  date  expression  is  a  memory  variable,  a  field,  or  any  function  that  returns 
date  type  data. 


Example 


To  display  a  date  in  DMY  format: 

.  leapdate  =  {02/29/35} 

02/29/88 

.  ?  tWCLeopdate) 

29  February  88 


See  Also 

CDOW(),  CMONTH(),  DATE(),  DOW(),  MDY(),  MONTH (),  SET  CENTURY, 
SET  DATE(),  YEAR() 
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DOW() 


The  DOW()  function  returns  a  number  that  represents  the  day  of  the  week  from 
a  date  expression  starting  with  Sunday  as  day  1. 


Syntax 

DOW( <  expD>  ) 


Usage 

The  date  expression  is  a  memory  variable,  a  field,  or  any  function  that  returns 
date  type  data. 


Examples 

If  the  system  date  is  05/13/88: 

.  ?  DCVQATEO) 

6.00 

To  store  the  day  of  the  week  from  the  system  date  to  the  memory  variable 
Dayofweek: 


.  STORE  DCUQATEO)  TO  Dayofvcek 
6.  CD 

.  ?  OeyoTueek 

6.00 

To  determine  the  number  of  the  day  of  the  week  for  a  date  197  days  in  the 
future: 


.  ?  DCUOHTEO  +  197) 

7.00 


See  Also 

CDOWQ,  DATE(),  DAY() 
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DTOCQ 


The  DTOC()  function  converts  a  date  to  a  character  string. 

Syntax 

DTOC(<  expD>  ) 


Usage 

This  function  is  used  to  store  a  date  as  a  character  type  memory  variable  or  to 
compare  a  date  to  a  character. 


Examples 

To  store  the  system  date  as  a  character  type  memory  variable  (assuming  the  sys¬ 
tem  date  is  05/13/88): 

.  STORE  DTOCCDATEO)  TO  testdate 
05/13/88 

.  ?  TYFEC  testdate") 

C 


lb  connect  a  date  variable  to  a  character  string  for  use  as  text: 

.  STORE  DATEO  TO  testdate 
Q5/13/8B 

.  ?  TYFEC  testdate’) 

D 

.  STORE  ' The  <±te  isC-H)TOC( testdate)  TO  text 
The  date  is:  05/13/88 


See  Also 

CTODQ,  DATE(),  SET  CENTURY,  SET  DATE 
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DTOR() 


The  DTOR()  function  converts  degrees  to  radians. 

Syntax 

DTOR(  <  expN  >  ) 


The  expression  <  expN>  is  the  size  of  the  angle  measured  in  degrees.  The 
DTOR()  function  returns  the  angle  size  in  radians. 

Convert  minutes  and  seconds  to  decimal  fractions  of  a  degree  before  using  this 
function. 


Examples 

.  ?  0KRC18O) 
3.14 


Convert  60  degrees  30  minutes  15  seconds  to  radians: 


.  DKRGS&525) 
1.(356 


Substitute  a  variable: 


.  VariabLel  =  12 

12.00 

.  Variable  =  DWRCVariabLel) 

.21 


See  Also 

ACOSQ,  AEANQ,  ATN2(),  COSQ,  RTODQ,  SET  DECIMALS,  SIN() 
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DTOS() 


The  DTOS()  function  converts  a  date  variable  to  a  character  string  for  indexing. 

Syntax 

DTOS(<  expD>  ) 

Usage 

Use  this  function  when  you  need  to  index  on  a  date  expression  plus  a  character 
expression.  The  variable  <  expD>  is  a  date  expression.  This  function  converts 
the  specified  date  to  a  character  string  of  the  form  CCYYMMDD  regardless  of 
the  SET  CENTURY  or  SET  DATE  setting. 


Example 

.  LSE  Transact 

.  INDEX  CN  DTOSWateJrens)  +  OrderJd  TO  Trjate 
10CK  indexed  12  Records  indexed 


LIST  tfIXT  6  DateJrers,  OrderJd 


Record#  DateJrar*  OrderJd 
1  (2/03/88  87-105 


2  (2/10/88  87-105 

3  02/12/88  87-107 

4  02/23/ 88  87-1 0B 

5  03/09/88  87-109 

6  03/09/88  87-110 


See  Also 

CTOD(),  DATEQ,  DTOCQ,  SET  CENTURY,  SET  DATE 
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The  EOF()  function  indicates  the  end  of  a  File.  A  logical  true  (.T.)  is  returned 
when  the  last  logical  record  of  the  specified  database  file  is  passed. 

Syntax 

EOF([  <  alias  >  ]) 


Usage 

When  EOF()  is  true,  RECNO()  is  RECCOUNT()  +  1.  Also,  certain  commands 
(such  as  SKIP)  return  the  error  message  End  of  File  encountered. 


Special  Cases 

If  no  database  file  is  in  USE  in  the  specified  work  area,  EOF()  returns  a  logical 
false  (.F.). 


Example 

To  test  for  the  end  of  a  file: 

.  USE  Client 
.  GO  BOTTOM 
.  ?  EOF  O 
F 

.  sap 

.  ?  B3FO 
T 


See  Also 


BOF(),  ERRORQ,  FOUND() 
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ERRORQ 


The  ERROR()  function  returns  the  number  corresponding  to  the  dBASE  IV 
error  message  that  caused  an  ON  ERROR  condition. 


Syntax 

ERRORQ 


The  ERRORQ  function  returns  the  error  message  number  of  the  error  trapped 
by  the  ON  ERROR  command.  Error  messages  and  their  numbers  are  listed  in 
Appendix  A  of  this  manual,  where  appropriate  corrective  actions  are  suggested 
when  possible. 

Ibrminate  unrecoverable  errors  with  the  CANCEL  command. 


NOTE 

For  this  function  to  return  a  number,  an  ON  ERROR  command  must  be 
active.  RETURN  and  RETRY  clear  the  error  number  and  message  that 
dBASE  IV  recorded. 


Example 

In  a  program  that  prompts  the  user  for  the  name  of  a  PFS  file  to  import,  a  rou¬ 
tine  is  needed  to  trap  the  error  message  Not  a  PFS  flic.  The  value  of  this 
ERRORQ  is  140. 

*  htain.PRS 
CNERRCR  DO  Err_proc 

ACCEPT  "Biter  the  name  of  the  PFS  file:  ’  TO  filename 
IMPORT  FBCW  ^filename.  PIPE  PFS 

*  PKXHXRE  Err_proc 
CN  EFRCR 

DO  CASE 

CASE  ERRCRO  =  140 

?  "Sfilename.  is  not  a  PFS  file." 

* 

* 

* 

BDCASE 

RETIFN 
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ERRORQ 


See  Also 

DEBUG,  LINENO(),  MESSAGE*),  ON  ERROR,  PROGRAM(),  RETRY,  RETURN 
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The  EXP()  function  returns  the  value  that  results  from  raising  the  constant  e  to 
the  power  of  <  expN>  . 


Syntax 

EXP(<  expN  >  ) 


Usage 


Given  the  equation  e*-  y,  <  expN>  is  the  value  ofx.  For  any  exponent  x  to 
the  base  e,  the  function  returns  the  value  of  y  from  the  equation.  The  returned 
value  is  a  real  number.  The  SET  DECIMALS  setting  determines  the  accuracy  of 
the  displayed  answer. 

Examples 

Any  number  raised  to  the  power  of  1  equals  the  number.  Raising  e  to  1  returns 
the  value  of  e. 

.  ?  EXPd.QOD) 


2.72 


To  get  the  value  at  the  end  of  a  logarithmic  calculation: 

.  x  -  Log(25)  *  Leg (25) 

6.44 

.  ?  EXPCx) 

625.00 

See  Also 

LOG(),  SET  DECIMALS,  SET  PRECISION 
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FIELD() 


The  FIELDQ  function  returns  the  field  name  of  the  specified  field  number  from 
the  file  structure  of  the  selected  database  file. 


Syntax 

FIELD([alias  name]) 


Usage 

The  FIELD()  function  returns  all  Held  names  in  uppercase  letters.  If  the 
numeric  expression  is  not  between  1  and  255,  or  if  the  numeric  expression 
refers  to  an  unused  field,  dBASE  IV  returns  a  null  string.  For  example,  if  you 
have  a  Hie  structure  with  28  field  names,  and  you  ask  for  any  field  above  the 
28th  field  name,  you  get  a  null  string. 

Because  the  FIELDQ  function  addresses  each  field  by  its  number,  it  enables 
you  to  handle  fields  as  an  array. 


Example 

Use  the  Qient  database  file. 


.  USE  Client 
.  ?  FIELD® 

LASTWE 
.  ruitxr  = 2 

2.00 

.  Mfield  =  FlELDCwixr) 
CLIBJT 


See  Also 

DBFQ,  LUPDATEQ,  RECCOUNTQ,  RECSIZEQ 
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FILE() 


The  FILE()  function  Verifies  the  existence  on  a  selected  disk  of  a  specified  file¬ 
name  and  returns  logical  true  (.T.)  if  the  file  exists  on  the  disk. 

Syntax 

FILE(<  expC>  ) 

Usage 

The  F1LE()  function  requires  both  the  filename  and  its  extension.  If  the  file  is 
not  on  the  default  drive  and  directory,  you  must  give  the  complete  file  specifi¬ 
cation  including  the  drive  and  directory  name. 

The  F1LE()  function  is  not  case  sensitive. 


Examples 

If  the  default  drive  is  C  and  Client.dbf  is  on  drive  A,  this  function  does  not  find 
it  without  the  drive  specification. 

.  ?  FILEC Client. d>r) 

.F. 


It  does  not  find  the  file  without  the  extension: 


.  ?  FIL£CA:Clientr) 
.F. 


Give  the  complete  file  specification: 

.  ?  FILECA:Climt.dbr) 

.T. 


Save  the  filename  to  a  memory  variable  for  fast  file  retrieval: 

.  STORE  mA:Cl  ient.cbf  TO  Test 
A:Client.dbf 
.  ?  FILECest) 

.T. 


See  Also 

SET  DEFAULT,  SET  PATH 
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FIXEDQ 


The  FIXED  ()  function  converts  long,  real  floating  point  numbers  to  binary 
coded  decimal  numbers. 

Syntax 

FIXED<<  expF>  ) 

Usage 

The  FIXED()  function  is  used  to  convert  type  F  (IEEE  long,  real  floating  point) 
numbers  to  type  N  (binary  coded  decimal)  numbers.  Some  levels  of  precision 
may  be  lost  in  the  conversion.  Both  number  types  support  scientific  notation. 

If  an  expression  uses  both  numeric  types,  all  numbers  are  converted  to  type  F. 
The  range  is  between  10308  to  10'308. 

Examples 

To  convert  52556.234  to  a  type  N  number: 


.  Mem  =  52555^36 
52556.234 
.  ?  FIXEDCMem) 
525562346+04 


The  result  of  an  expression  that  contains  both  numeric  data  types  is  a  type  F 
number: 


.  ?  4 21.22  *  1.0DEKB 
42122D.00 


See  Also 

FLOATQ 
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FKLABELQ 


The  FKLABEL()  function  returns  the  name  assigned  to  the  specified  function 
key. 

Syntax 

FKLABEL(<  expN>  ) 

Usage 

You  may  program  a  total  of  28  keys:  9  function  keys,  and  19  function  key  com¬ 
binations  with  either  the  Shift  or  the  Ctrl  keys.  The  full-screen  SET  command 
shows  a  list  of  the  programmable  keys.  You  may  program  these  keys  from  the 
menus  of  the  full-screen  SET  command,  from  the  dot  prompt  with  the  SET 
FUNCTION  command,  or  from  the  Config.db  file.  (See  Chapter  6,  “Customizing 
dBASE  IV.”) 

The  FKLABEL()  function  returns  the  key  label  associated  with  the  function  key 
specified  by  <  expN >  .  Any  numeric  expression  from  1  to  28  is  valid. 

The  FI  function  key  is  dedicated  to  the  Help  function  and  is  not  programmable. 
FKLABEL()  starts  counting  the  function  keys  beginning  with  1  =  F2. 


Example 

To  determine  the  FKLABEL()  corresponding  to  a  function  key,  type  the  follow¬ 
ing  at  the  dot  prompt: 

.  ?FKUBEL(9) 

no 

See  Also 

FKMAXQ,  SET,  SET  FUNCTION 
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FKMAX() 


The  FKMAX()  function  returns  an  integer  representing  the  number  of  program¬ 
mable  function  keys  on  the  computer  keyboard. 


Syntax 

FKMAX() 

Usage 

The  FKMAX()  function  is  used  to  determine  the  maximum  number  of  program¬ 
mable  keys  supported  by  dBASE  IV. 

dBASE  IV  uses  the  FI  key  as  HELP,  and  the  Shift-FlO  keys  to  access  the  macro 
menu;  therefore,  these  keys  are  not  programmable.  The  F11  and  F12  function 
keys  of  101-key  keyboards  are  also  not  programmable. 

Example 

Find  the  total  number  of  programmable  keys: 

.  ?  rmxo 

28 


This  is  the  sum  of  F2  through  F10  (9  keys),  plus  Shift-FI  through  Shift-F9 
(9  keys),  and  Ctrt-FI  through  Ctri-F10(10  keys). 


See  Also 

FKLABELQ,  SET,  SET  FUNCTION 
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The  FLOAT()  function  converts  binary  coded  decimal  (type  N)  numbers  to  long, 
real,  floating  point  (type  F)  numbers. 


Syntax 

FLOAT(  <  expN  >  ) 


Usage 

The  expression,  <  expN>  ,  is  any  valid  type  N  number.  This  numeric  data  is 
converted  to  a  type  F  number. 


Examples 

To  convert  1.234E+  02  to  a  floating  point  number: 


.  !%ar  =  1.25C&K2 
1oZ34BQ2 
.  ?  FLCATOkar) 
123.40 


When  both  number  types  are  included  in  the  same  expression,  the  result  is  a 
type  F  number: 

.  ?  2.3U5&CB  *  3.1 
7267.95 


See  Also 
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FLOCKQ 


The  FLOCKQ  function  provides  explicit  file  locking  from  either  the  dot  prompt 
or  from  within  dBASE  IV  programs. 

Syntax 

FLOCK([aliasJ) 

Usage 

The  FLOCK()  function  prevents  multiple  users  from  simultaneously  updating 
the  same  file.  Use  the  FLOCKQ  function  to  lock  all  the  records  in  a  file  for 
operations  involving  the  whole  file.  Use  the  RLOCKQ  or  LOCKQ  function  to 
lock  one  record  in  a  file  for  efficient  multi-user  file  access. 

This  explicit  locking  feature  is  in  addition  to  the  automatic  locking  that 
dBASE  IV  provides  when  you  use  commands  that  work  with  the  entire  database 
file.  See  the  SET  LOCK  command  in  Chapter  3  of  this  manual  for  a  list  of  all 
dBASE  IV  commands  that  provide  automatic  file  locking,  and  the  level  of  lock 
each  provides. 

A  locked  file  cannot  be  modified  by  another  user  until  the  lock  is  released. 
However,  FLOCKQ  lets  other  users  have  read-only  access  to  view  the  locked 
file. 

If  you  specify  the  optional  alias  name  with  FLOCKQ,  dBASE  IV  attempts  to 
lock  the  file  in  the  designated  work  area.  If  you  do  not  specify  an  alias, 
dBASE  IV  locks  the  file  in  the  current  work  area.  The  alias  name  you  specify 
must  be  the  same  name  as  the  ALIAS  keyword  or  the  default  filename.  You  may 
not  use  a  work  area  number  (1  through  10)  or  letter  (A  through  J). 

If  the  file  lock  attempt  is  successful,  dBASE  IV  opens  the  file  for  exclusive  use, 
and  FLOCKQ  returns  a  logical  true  (.T.).  The  file  remains  locked  until  you: 

■  Unlock  it  with  the  UNLOCK  command 

■  Close  the  file 

■  Quit  dBASE  IV 

If  the  file  is  already  locked  by  another  user,  FLOCKQ  returns  a  logical  false 
(F.). 

If  you  lock  a  file  while  it  is  actively  related  to  other  open  files,  then  all  the  files 
in  the  relation  are  automatically  locked.  Unlocking  any  one  of  the  related  files 
automatically  unlocks  the  other  files. 
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FLOCK() 


Example 

The  following  program  file  segment  uses  the  FLOCK()  function  to  lock  a  data¬ 
base  file.  If  the  lock  is  unsuccessful  after  250  attempts,  the  procedure  Time_out 
is  executed: 


SET  REPROCESS  TO  250 
IF  .NJT.  RJXKO 
DO  Tim*_£ut 
RETLRSI 
BDIF 


See  Also 

ACCESS(),  RLOCK()/LOCK(),  SET  LOCK,  SET  REPROCESS,  UNLOCK 
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FLOOR() 


The  FLOOR()  function  calculates  and  returns  the  largest  integer  that  is  less 
than  or  equal  to  the  value  of  the  specified  numeric  expression. 


Syntax 

FLOOR(<  expN  >  ) 


Use  this  function  to  find  the  largest  integer  that  is  less  than  or  equal  to  a  given 
value.  The  returned  value  is  the  same  data  type  as  the  specified  numeric  expres¬ 
sion  <  expN  >  . 


Example 

.  first  =  121 

121 .00 

.  FLOORf first  /  1d> 

0.12 


See  Also 

CEILINGQ,  INT(),  ROUND() 
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FOUND() 


I 


The  FOUND()  function  returns  a  logical  true  (.T.)  if  the  previous  FIND, 
LOCATE,  SEEK,  or  CONTINUE  command  was  successful. 


Syntax 

FOUND([  <  alias  >  )) 


Usage 

FOUND()  is  used  in  programming  to  branch  on  the  result  of  a  search 
command.  There  is  one  FOUNDQ  per  work  area. 

If  files  are  linked  by  a  SET  RELATION  TO  command,  dBASE  IV  searches  the 
related  database  files  as  you  move  in  the  active  file  with  FIND,  LOCATE,  SEEK, 
or  CONTINUE  commands.  FOUNDQ  is  set  to  true  (.T.)  or  false  (.F.)  both  in  the 
active  work  area  and  in  the  related  work  areas,  depending  on  the  result  of  the 
search  command. 

If  you  move  the  record  pointer  with  any  command  other  than  FIND,  LOCATE, 
SEEK,  or  CONTINUE,  the  result  of  FOUNDQ  is  .F. 


Example 

lb  check  the  results  of  a  search  on  an  unindexed  file: 
.  USE  Client 

.  LOCATE  FOR  Lastnane  =  •fitters' 

Record  =  4 
.  ?  FVUOO 
.T. 

.  CCNTTALE 
Bid  of  LOCATE  sccpe 
.  ?  FOADO 
.F. 


See  Also 

CONTINUE,  EO  ),  LOCATE,  LOOKUPQ,  SEEK,  SEEKQ, 

SET  RELATION 


I 
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The  FV()  function  calculates  the  future  value  of  equal  regular  deposits  into  an 
investment  that  yields  a  fixed  interest  rate  for  a  certain  number  of  time  periods. 


Syntax 


FV(<  payment  >  ,  <  rate  >  ,  <  periods  >  ) 


Usage 


<  Payment >  is  a  numeric  expression  which  can  be  negative  or  positive. 

<  Rato  is  interest  rate.  This  is  always  a  positive  number.  It  is  assumed  that 
the  interest  is  compounded  once  each  period.  If  you  use  a  yearly  interest  rate 
and  compound  monthly,  the  <  rate>  expression  is  your  rate  divided  by  12 
months. 

<  Periods  >  is  a  numeric  expression  that  represents  the  number  of  payments. 
Each  period  is  the  equal  time  interval  between  payments. 

The  output  of  FV()  is  a  fixed  point  number  representing  the  total  deposits  plus 
the  interest  generated  and  compounded. 

Example 

c  DFUT  ’Biter  payment:  ’  TO  payment 
Enter  payment:  1.00 

.  DfUT  ' Biter  interest  rate:  '  TO  rate 
Enter  interest  rate:  .02 

.  IffUT  "Biter  ruiber  of  payment  '  TO  periods 
Enter  rurtoer  of  payments:  24 
.  ?  FV (payment,  rate,  periods) 


30.42 


See  Also 


CALCULATE  PV() 
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GETENVQ 


The  GETENV()  function  returns  the  contents  of  a  DOS  environmental  system 
variable  such  as  PATH  or  COMSPEC.  The  name  of  the  system  variable  may  be 
entered  as  a  character  string,  a  character  variable,  or  a  combination  of  both 

Syntax 

GETENV(<  expC>  ) 


Usage 

GETENV()  enables  you  to  check  the  settings  of  the  DOS  environment 
commands.  If  dBASE  IV  does  not  find  the  environment  command  parameter,  it 
returns  a  null  string. 

The  variables  to  an  operating  system  environment  are  commands  such  as 
PROMPT,  PATH,  and  COMSPEC.  See  your  DOS  operating  system  reference 
manual  for  a  list  of  the  system  environment  commands.  These  are  usually 
implemented  from  the  Autoexec.bat  file. 

You  may  also  need  to  refer  to  the  SHELL  command  in  the  same  manual  if  you 
need  to  increase  the  environment  space.  You  may  run  out  of  DOS  environment 
space  if  you  use  many  DOS  configuration  commands  or  a  long  path  statement. 


Example 

Assume  that  your  default  drive  is  C  and  you  have  a  path  statement  with  several 
directories.  To  find  the  DOS  setting  for  "PATH": 

.  ?  GETBWCpatff) 

C:\;C:\DOS;C:\DBASE... 

All  other  directories  you  may  have  in  your  path  statement  are  displayed. 

See  Also 

OS() 
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IIF()  stands  for  immediate  IF  and  is  a  shortcut  to  the  IF...ENDIF  programming 
construction. 


Syntax 

IIF(<  expL>  ,<  expl  >  ,<  exp2>  ) 


Usage 


You  can  use  this  function  from  the  dot  prompt  or  inside  programs.  If  the  logi¬ 
cal  expression  is  true,  IIF()  returns  the  result  of  the  first  expression;  otherwise, 
it  returns  the  result  of  the  second  expression. 

<  expl>  and  <  exp2>  can  be  character,  numeric,  logical,  or  date  expres¬ 
sions.  Both  expressions  must  be  the  same  type. 

You  can  use  the  IIF()  function  from  the  dot  prompt,  or  with  commands  such  as 
CREATE/ MODIFY  REPORT  and  CREATE/ MODIFY  LABEL.  The  IIF()  function 
allows  you  to  replace  a  field  or  a  value  in  an  expression  with  one  of  two  values, 
based  on  the  evaluation  of  a  condition. 


Examples 


In  the  following  program,  you  can  replace  the  first  set  of  commands  with  the 
one  IIF()  command  line  that  immediately  follows  them.  This  example  uses  the 
IF...ENDIF  structure: 

IF  Sex  =  'F 

=  "Ms.  *  +  Last_rwB 

ELSE 

Wnare  =  "ft*.  *  +'  LasLname 
B©IF 

This  is  the  one-line  replacement  using  IIF(): 

Wname  =  IIFCSex  =  "F,  **•.  ")  ♦  Lastiw* 

You  could  use  this  IIF()  construction  to  print  labels  with  the  appropriate  title 
by  including  IIF()  in  the  label  contents  area. 

If  you  have  a  database  file  with  the  date  fields  Start.date  and  End.  date,  you 
can  extend  the  End.  date  by  30  days  if  that  date  has  already  passed. 

In  the  interactive  mode: 

.  RERJCE  ALL  ErxLchte  UTTH  IIFfBrtcbte  >  M7FO,  EncUate,  BrUate  *  JD 


4-54 


FUNCTIONS 


PAGE:  55  SESS:  M  FpI  f1«r  25  15:31:28  1  988 

?/•!  I  J  obz/CLS_pi«nh«t /GRP_/n»nh«t/JOB_m«n  I angraf  /O I  V_lrchapA 


IIF() 


If  you  have  already  assigned  a  value  to  the  logical  memory  variable  Is_error, 
the  following  routine  converts  the  variable  to  a  number,  then  saves  it  in  the 
numeric  memory  variable  Error_code.  If  Is_error  is  true,  the  new  memory 
variable  is  1,  otherwise  it  is  0. 


error_pode  *  IIF(i*_emor,  1,  Q> 

See  Also 

The  Programming  with  d BASE IV manual 
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INKEY() 


The  INKEY()  function  returns  an  integer  representing  the  most  recent  key 
pressed  by  the  operator.  It  does  not  halt  program  execution. 


Syntax 

INKEY() 

Notes 

The  INKEY()  function  returns  an  integer  between  0  (zero)  and  255,  corres¬ 
ponding  to  the  decimal  ASCII  value  of  the  character  in  the  type-ahead  buffer. 

If  there  are  several  characters  in  the  type-ahead  buffer,  INKEY()  returns  the 
ASCII  value  of  the  first  character  in  the  buffer  and  clears  the  character  from 
the  type-ahead  buffer. 

INKEYQ  returns  a  zero  if  no  key  is  pressed. 

INKEYQ  returns  the  control-key  equivalent  of  special  keys,  such  as  arrow  keys 
and  Ctrl-Home. 

This  function  is  often  used  in  programs  as  a  condition  for  branching.  It  lets  you 
use  function  and  cursor  movement  keys  within  a  dBASE  IV  program. 

The  keyboard  codes  for  normal,  control  and  shift  combinations  for  all  alphanu¬ 
meric  keys  are  listed  in  Appendix  H,  “ASCII  Chart.”  The  values  represented  by 
Ctri-S  (decimal  19)  and  Ctrt-(  (decimal  27  or  Esc)  are  not  trapped  by  INKEYQ. 

Keyboard  codes  returned  by  INKEYQ  for  function  keys  and  key  combinations 
are  listed  in  Table  4-1.  Keyboard  codes  returned  by  INKEYQ  for  the  Alt  key 
combined  with  the  alphanumeric  keys  are  listed  in  Thble  4-2.  The  Alt  codes  are 
the  same  for  uppercase  and  lowercase  letters.  The  values  returned  are  decimal. 
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INKEY() 


1 


Table  4-1  Function  key  NKEY()  values 


Keys 

Alone 

With  art 

With  Alt 

With  Shift 

FI 

28 

-  11 

0 

-  21 

F2 

-  2 

-  12 

0 

-  22 

F3 

-  3 

-  13 

0 

-  23 

F4 

-  4 

-  14 

0 

-  24 

F5 

-  5 

-  15 

0 

-  25 

F6 

-  6 

-  16 

0 

-  26 

F7 

-  7 

-  17 

0 

-  27 

F8 

-  8 

-  18 

0 

-  28 

F9 

-  9 

-  19 

0 

-  29 

FIO 

-  10 

-  20 

0 

Macro  menu 

Table  4-2  Alt  key  combination  INKEY Q  values 

With  Letters 

With  Numbers 

a  -  435 

n 

-  422 

1-451 

b  -  434 

0 

-  421 

2  -  450 

c  -  433 

P 

-  420 

3  -  449 

d  -  432 

q 

-  419 

4  -  448 

e  -  431 

r 

-  418 

5  -  447 

f  -  430 

s 

-  417 

6  -  446 

g  -429 

t 

-  416 

7  -  445 

h  -  428 

u 

-  415 

8  -  444 

i  -  427 

V 

-  414 

9  -  443 

j  -  426 

w 

-  413 

0  -  442 

k  -  425 

X 

-  412 

1  -  424 

y 

-  411 

m  -  423 

z 

-  410 
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INKEYQ 


Example 


The  following  program  segment  shows  branching  to  two  different  procedures 
depending  on  the  key  the  user  presses. 


DO  VHILE  .T. 
i  =0 

i  =  INCEYO 
DO  CASE 

CASE  <HKi>  $  "Qcp 
RETUN 

CASE  Ofl(i)  $  "Aal" 

DO  <procedre  1> 
CASE  Cl-R(i)  $  "EbZ* 

DO  <procedre  2> 

BDCASE 

BO 00 


See  Also 

CHR(),  LASTKEY(),  ON  KEY,  READ,  READKEY(),  SETTYPEAHEAD 
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INT() 


The  INT()  function  truncates  any  numeric  expression  to  an  integer. 

Syntax 

INT(<  expN  >  ) 

Usage 

You  can  discard  all  digits  to  the  right  of  the  decimal  point  in  a  numeric  expres¬ 
sion  by  using  INT(). 


Example 


To  convert  the  number  10.23  to  an  integer: 

.  ?  JNTCI0.25) 

10.QD 

.  STCRE  10.25  TO  x 
10.Z5 

.  STCRE  JNTC10.25)  TO  x 
10 


See  Also 

CEILINGO,  FLOORQ,  ROUND() 
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ISALPHA() 


The  ISALPHA()  function  returns  a  logical  true  (.T.)  if  the  specified  character 
string  begins  with  an  alphabetical  character. 

Syntax 

ISALPHA<<  expC>  ) 

Usage 

An  alphabetical  character  is  any  upper  or  lowercase  letter  between  a  and  z. 

Use  this  function  to  determine  whether  or  not  a  string  begins  with  an  alphabeti¬ 
cal  character. 

Examples 

To  test  whether  a  string  begins  with  an  alphabetical  character: 

.  ?  ISALFMCabclZ?) 

•T. 

.  ?  ISALFMC&C1Z?) 

.T« 

.  ?  ISALflUC  1Z5abc“) 

.F. 

See  Also 

ISLOWERQ,  ISUPPERQ,  LOWERQ,  UPPER() 
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ISCOLOR() 


The  ISCOLOR()  function  returns  a  logical  true  (.T.)  if  a  computer  is  capable  of 
displaying  color. 

Syntax 

ISCOLOR() 

Usage 

The  ISCOLORQ  function  enables  developers  to  design  applications  for  both 
color  or  monochrome  environments.  This  function  checks  the  setting  of  the 
DOS  MODE  command  and  returns  a  true  (.T.)  if  it  finds  that  MODE  is  equal  to 
CO80  or  CO40. 

Example 

To  set  the  color  environment  from  within  a  program,  you  could  execute  the  fol¬ 
lowing  commands  in  a  dBASE  IV  program: 

IF  ISCCLCRO 

SET  CCUCR  TO  GR/B^W/R^GR 
ELSE 

SET  CCLOR  TO  Wf 
BOIF 

If  ISCOLORQ  returns  true  (.T.),  this  program  could  continue  to  define  text  and 
highlight  colors  for  a  color  display.  Otherwise,  it  would  set  the  display  for 
monochrome. 

See  Also 

SET  COLOR,  SET  DISPLAY” 
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ISLOWERQ 

The  ISLOWER()  function  returns  a  logical  true  (.T.)  if  the  specified  character 
string  begins  with  a  lowercase  alphabetical  character. 

Syntax 

ISLOWER(<  expC>  ) 

Usage 

Use  this  function  to  evaluate  and  manipulate  character  strings. 

ISLOWERQ  returns  a  logical  false  (.F.)  when  either  an  uppercase  letter  or  a 
non-alphabetical  character  is  in  the  first  position  of  the  string. 


Example 

To  test  whether  a  string  begins  with  a  lowercase  alphabetical  character: 

.  ?  ISUZERCabcIZT) 

.T. 

.  ?  ISUMRCJBCIZ?) 

.F. 

.  ?  ISUJUERC  12atxf ) 

.F. 


See  Also 

ISALPHAQ,  ISUPPERQ,  LOW!  R(),  UPPERQ 
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ISMARKEDQ 


The  ISMARKEDQ  function  checks  the  current  work  area,  or  the  optional  alias, 
to  determine  if  dBASE  IV  has  placed  a  marker  in  the  database  file  header  to 
indicate  that  the  file  is  in  a  state  of  change. 


Syntax 

ISMARKED([  <  alias  >  ]) 

Usage 

This  function  answers  the  question  of  whether  a  database  is  in  an  integral  state 
or  in  a  state  of  change.  If  the  database  file  header  is  marked  for  change, 
ISMARKED()  returns  a  logical  true  (.T.).  If  the  database  file  is  not  marked,  this 
function  returns  a  logical  false  (.F.). 


Example 

See  the  example  under  the  COMPLETEDQ  function  in  this  chapter. 

See  Also 

BEGIN  TRANSACTION/END  TRANSACTION,  COMPLETEDQ,  ROLLBACK 
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ISUPPERQ 


The  ISUPPER()  function  returns  a  logical  true  (.T.)  if  the  specified  character 
string  begins  with  an  uppercase  alphabetical  character. 

Syntax 

ISUPPER(<  expC>  ) 


Usage 

Use  this  function  to  evaluate  and  manipulate  character  strings. 

ISUPPERQ  returns  a  logical  false  (.F.)  when  either  a  lowercase  letter  or  a  non 
alphabetical  character  is  in  the  first  position  of  the  string. 

Example 

To  test  whether  a  string  begins  with  an  uppercase  alphabetical  character: 

.  ?  ISLPFERCSBC1Z?) 

.T. 

.  ?  ISLFFERCabc  72T ) 

.F. 

.  ?  ISLPFERC12GT) 

.F. 


See  Also 

ISALPHAQ,  ISLOWERQ,  LOW  SR(),  UPPERQ 
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KEY() 


The  KEY()  function  returns  the  key  expression  for  the  index  file  specified  by 
<  expN  >  . 

Syntax 

KEY([<  .mdx  file>  ,]  <  expN>  [,<  alias  name>  ]) 


Usage 

If  you  give  an  .mdx  filename  to  the  function,  the  numeric  expression  is  inter¬ 
preted  in  reference  to  that  file.  If  the  specified  file  does  not  exist,  then  this 
function  returns  a  null  string. 

If  you  do  not  name  an  .mdx  file,  then  dBASE  IV  considers  all  open  index  files 
in  the  work  area  to  interpret  <  expN>  . 


See  Also 

MDX(),  NDX(),  ORDERQ,  TAG() 
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LASTKEYQ 


The  LASTKEYQ  function  returns  the  decimal  ASCII  value  of  the  last  key 
pressed. 

Syntax 

LASTKEYQ 

Usage 

This  function  returns  the  ASCII  value  of  the  last  key  pressed  by  the  operator.  It 
returns  the  same  values  as  INKEYQ. 

LASTKEYQ  is  used  in  programming  to  get  the  value  of  the  operator’s  response 
and  to  cause  a  program  response  (such  as  displaying  a  menu  or  a  message,  exe¬ 
cuting  a  command  or  a  procedure). 


Example 

Use  a  function  key  as  an  alternate  key  for  terminating  a  full-screen  command. 
To  determine  what  the  terminating  key  was,  use  LASTKEYQ  in  a  program  file: 


SET  RJCTICN  5  ID  (HWZ3)  8&  OR<23)=Ctrl-End  key  value. 
DO  WHILE  .T. 

*(^GET  variables 


C-3  ■^£‘S,/9A  jT£ 


3  19,10  SAY  "Press  F5  to  show  a  list  of  Items. 
READ 

*£3Check  for  fmcticn  key  5  exit. 

IF  LASTKEYO  =€5 
DO  Shcwi  tern 
inrp 
ELSE 
EXIT 
BCIF 
BtoOO 


C^>  S/>/?A/fr£  HTThi 


/  /Y  a  5 


See  Also 

INKEYQ, READKEYQ 
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LEFTQ 


The  LEFT()  function  returns  a  specified  number  of  characters  from  a  character 
string  or  memo  field,  starting  from  the  first  character  on  the  left. 

Syntax 

LEFT(<  expC>  ,<  expN  >  ) 


The  LEFT()  function  lets  you  retrieve  the  first  part  of  a  character  string  or  a 
memo  field.  This  is  the  same  as  defining  the  SUBSTRQ  function  with  a  starting 
position  of  one,  and  the  number  of  characters  to  extract  with  <  expN  >  . 

The  numeric  expression  defines  the  number  of  characters  to  extract  from  the 
character  string.  If  the  numeric  expression  is  zero,  a  null  string  is  returned. 

If  the  numeric  expression  is  greater  than  the  length  of  the  character  string, 
LEFT()  returns  the  entire  string. 

Examples 

lb  extract  the  first  three  characters  from  a  character  string: 

.  ?  LEFTCatcdsfjJ) 
abc 

See  Also 

AT(),  LTRIMQ,  RIGHTQ,  RTRIMQ,  STUFFQ,  SUBSTR(),  TRIMQ 
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The  LEN()  function  returns  a  numeric  value  indicating  the  number  of  charac¬ 
ters  in  a  specified  character  string  or  memo  field. 

Syntax 

LEN(<  expC>  ) 

Usage 

Use  this  function  to  determine  the  number  of  characters  in  a  database  field  or  a 
memo  field.  This  function  returns  a  zero  if  the  field  contains  a  null  string. 

Examples 

To  find  the  actual  number  of  characters  in  a  database  field,  use  TRIM()  in  con¬ 
junction  with  LEN(): 

.  USE  Client 
.  GOTO  2 
.  ?  Lastrm 
Bailey 

.  ?  LBKLastname) 

15.00 

.  ?  LBiCmiMClastrern)) 

6.CD 

LEN()  also  works  on  memo  fields: 

.  ?  LBiCCL  icnjiist) 


366.00 


See  Also 


TRIMQ 
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LIKEQ 


LIKE()  is  a  programming  function  usedjor  wildcard  comparisons.  It  is  also 
used  to  support  the  predicate  in  the  set  ■^■'oriented  SQL  language 

A 


r 


Syntax 

LIKE  (<  pattern  >  ,  <  expC>  ) 

Usage 

Use  this  function  to  compare  the  string  on  the  left  with  the  string  on  the  right. 
The  string  on  the  left  contains  a  pattern  including  wildcard  symbols,  the  string 
on  the  right  is  compared  to  this  pattern.  This  function  returns  a  logical  true 
(.T.)  or  false  (.F.). 

"IWo  wildcard  characters  are  allowed  in  the  pattern  string:  the  asterisk  (*)  and 
the  question  mark  (?).  The  asterisk  stands  for  any  number  of  characters,  and 
the  question  mark  stands  for  a  single  character.  Both  wildcard  characters  may 
be  used  anywhere  and  more  than  once  in  the  pattern  string. 

LIKEQ  *abc*  .astring)  will  return  a  true  value  if  the  character  variable  or  field 
astringt nds  in  the  string  'abc*.  Similarly,  LIKE  ('*abc*',any  string)  will  return 
a  true  value  if  any  string  contains  the  'abc*  sequence  anywhere  in  it.  The  func¬ 
tion  is  case  sensitive;  the  wildcard  characters  may  stand  for  uppercase  or  low¬ 
ercase  letters.  The  defined  part  of  the  string  must  match  the  case  of  the  string 
you  are  looking  for  with  the  LIKE()  function. 

Examples 

The  LIKEQ  function  lets  you  use  wildcard  symbols  anywhere  in  a  string,  and  to 
use  them  as  often  as  needed. 

.  ?  LIKE Cabr*'/ abracadabra") 

.T. 

.  UXE  C  7a*&*" /beta  au  rhjf) 

.T. 

.  LDdC  Ta****/ barber*1) 

.T. 

.  LIKE C  7a*a*/bfirbanT) 

.F. 

See  Also 

SOUNDEXQ 
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LINENO() 


LINENO()  returns  the  file  relative  line  number  of  the  line  that  is  about  to  be 
executed  in  a  command  or  procedure  file. 


Syntax 

LINENO() 


Usage 

The  LINENO()  function  enables  developers,  when  in  the  Debugger,  to  set 
breakpoint  conditions  to  stop  a  program  at  a  specific  line. 

If  you  use  the  LINEN 0()  function  in  the  Breakpoint  window  of  the  Debugger, 
the  Debug  window  becomes  active,  and  you  can  enter  commands  at  the  Action 
prompt. 

If  the  command  or  procedure  you  are  executing  consists  of  more  than  one  line, 
LINENO()  returns  the  first  line  number  regardless  of  which  line  you  are  on. 


See  Also 

PROGRAM*),  SET  DEVELOPMENT 
("The  Programming  with  dBASE  IV m  a 
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LKSYS() 


The  LKSYS()  function  determines  the  log-in  name  of  the  user  who  has  locked  a 
record  or  a  file,  and  the  date  and  time  of  the  lock. 


Syntax 

LKSYS(n) 

n  ■  0  returns  the  time  when  the  lock  was  placed, 
n  -  1  returns  the  date  when  the  lock  was  placed, 
n  —  2  returns  the  log-in  name  of  the  user  who  locked  the  record. 


This  function  will  return  a  null  string,  unless  the  person  who  has  locked  the  file 
has  used  the  CONVERT  command  to  create  an  invisible  field  of  8  to  24  charac¬ 
ters  in  the  active  database  file. 


Both  the  CHANGE()  and  the  LKSYS()  functions  read  the  contents  of  this  invisi¬ 
ble  field  called  __DBASELOCK  to  return  information.  If  CONVERT  is  used  with 
an  argument  of  8,  then  the  user  log-in  name  will  be  truncated,  and  LKSYSQ 
will  return  a  null  string.  To  get  the  full  user  log-in  name,  use  an  argument  of  24 
with  CONVERT. 

Use  this  function  to  get  information  about  the  status  of  a  locked  record  or  file. 
The  information  returned  by  LKSYS()  is  valuable  for  maintaining  work  flow  in 
a  multi-user  system. 

Whenever  you  place  an  explicit  lock  on  a  file  with  FLOCK(),  or  on  a  record 
with  RLOCKQ,  you  must  use  the  UNLOCK  command  to  release  these  files  to 
other  users  on  the  network.  Also,  dBASE  IV  automatically  locks  files  that  are 
called  up  with  commands  that  use  the  entire  database  file.  Commands  that 
place  an  automatic  lock  on  files  are  listed  in  Chapter  3,  under  SET  LOCK. 

See  Also 

CHANGE* ),  CONVERT,  FLOCK*),  RLOCK(),  SET  LOCK,  UNLOCK 
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LOG() 


The  LOG()  function  returns  the  natural  logarithm  of  a  specified  number. 


Syntax 

LOG(  <  expN  >  ) 


Usage 

The  natural  logarithm  has  a  base  of  e.  The  LOGQ  function  returns  the  exponent 
in  the  following  equation: 

='  -  y. 

jL  is  the  numeric  expression  used  by  the  LOGQ  function.  This  must  be  a  posi-  w  h  & /*£ 

tive  integer  for  the  value  of  <  expN >  .  LOGQ  returns  the  value  ofy,  which  is  a  ^ 

type  F  (long,  real)  number. 


Examples 

Determine  the  natural  log  of  e  which  equals  2.71828.  Any  number  raised  to 
itself  returns  a  1. 


.  SET  DECIMALS  TO  5 
.  ?  LOG  (2. 71 828) 

i.occn) 


Calculate  4*2  using  natural  logs.  Get  the  value  from  the  EXP()  function. 

.  SET  DECIMALS  70  2 
.  x  =4 

4.00 

•  y =2 

2.00 

.  ?  LCGCx  *  y) 

2.08 

.  ?  EXPQ.OB) 

8.00 


See  Also 

EXPO,  LOGIOO 
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LOGIOQ 


The  LOGIOQ  function  returns  the  common  log  to  the  base  10  of  a  specified 
number. 

Syntax 

LOG10(  <  expN  >  ) 


Usage 

The  LOGIOQ  function  returns  the  value  for  y  in  the  equation: 

LOGlO(x)  -  y 

X  is  the  numeric  expression  used  by  the  LOGIOQ  function.  This  must  be  a  posi¬ 
tive  integer  for  the  value  of  <  expN>  .  LOGIOQ  returns  the  value  of  y,  which  is 
a  type  F  (long,  real)  number. 

Examples 

.  SET  DECIMALS  TO  4 
.  7LCC10 (2.  iTiTl) 

0.3310 

To  calculate  2*2  using  base  10  logs: 

.  LcgIQGD-HcglOGD 
0.6021 

Use  either  one  of  the  following  expressions  to  get  the  antilog: 

.  no*y 

4 

or: 

.  TIOfy 

4 

See  Also 

EXPQ,  LOGQ 
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LOOKUPQ 


The  LOOKUP()  function  searches  for  a  a  record  and  returns  a  value  from  a 
field  in  a  specified  database  file. 

Syntax 

LOOKUP  (<  return  exp>  ,  <  look-for  exp>  ,  <  look-in  field  >  ) 

<  return  exp>  and  <  look-for  exp>  are  any  valid  dBASE  IV  expressions.  You 
must  specify  an  alias  when  referring  to  expressions  outside  the  active  work 
area. 

<  look-in  field  >  is  the  name  of  a  field  in  the  database  file  which  you  are 
searching.  dBASE  IV  searches  the  current  work  area,  unless  you  precede  the 
look-in  field  expression  by  an  alias  name  and  a  pointer. 


Usage 

dBASE  IV  performs  a  sequential  search  unless  you  have  an  available  index 
which  contains  the  <  look-in  field >  as  its  key  expression.  You  can  optimize 
the  search  by  having  open  .mdx  tags  and  .ndx  files. 

At  the  end  of  the  search,  dBASE  IV  positions  the  record  pointer  in  the  first 
record  of  the  active  database  file  where  the  'look-for  expression’  matches  the 
value  in  the  look-in  field.  If  no  match  is  found,  the  record  pointer  is  at  the  end 
of  the  file. 


Example 

In  this  example,  the  first  print  statement  (?)  is  used  to  demonstrate  that 
LOOKUPQ  moves  the  record  pointer  in  the  database  file  searched. 

To  retrieve  information  from  a  selected  database  file  not  in  the  current  work 
area: 


.  USE  Transact 

.  USE  CL  ient  ORDER  Cl  ientJd  IN  2 
tester  index:  CUENTUD 
.  ?  CL  ient  ->CL  ientJd 
AT001 

.  ?  UXXLPCCl  ient  ->CL  ient,Cl  ientMCL  ient  -XL  ientjd) 
RELIC  EVENTS 
.  SELECT  2 

.  DISPLAY  Client-id,  Client 
Record#  ClientJd  Client 

8  A1CD25  RELIC  EVBJTS 
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LOWER() 


The  LOWER()  function  converts  uppercase  letters  to  lowercase  letters. 


Syntax 

LOWER(<  expC>  ) 


Examples 

.  ?  UJUERC  THIS  IS  A  NICE  MT) 
this  is  a  nice  c fay 

.  STORE  "THIS  IS  A  NICE  DAT  TO  nicecby 

.  ?  nicedsy 

THIS  IS  A  NICE  DAY 

.  ?  nice&y  -  ' this  is  a  nice  day 
.F. 

.  ?  LChERCn iceday)=  "this  is  a  nice  day 
.T. 


To  convert  all  but  the  first  character  in  a  character  string  to  lowercase: 

.  charstring  =  "LFPEXAST 
IFPERCASE 

.  reustring  =  LEFT(charstrirg,1)  +  SLBSTR(LOB?(charstring)^D 
Upercase 


See  Also 

ISALPHAO,  ISLOWERQ,  ISUPPERQ,  UPPERQ 


LANGUAGE  REFERENCE 
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LTRIM() 


The  LTRIM()  function  removes  leading  blanks  from  a  character  string. 


Syntax 

LTRIM(<  expC  >  ) 


Usage 

Use  this  function  to  remove  leading  blanks. 


Example 

To  remove  leading  blanks  from  a  character  string  formed  from  a  number: 


.  ?  STRC11. 95^,2) 

11.95 

.  ?  LTRIKSmai.95^) 
11.95 


See  Also 

LEFTQ,  RIGHTO,  RTRIM(),  STR(),  SUBSTRQ,  TRIM() 
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LUPDATEQ 


The  LUPDATEO  function  returns  the  date  of  the  last  update  of  the  specified 
database  file. 


Syntax 

LUPDATE([  <  alias  >  ]) 

Usage 

This  function  displays  the  last  date  when  the  active  database  file  was  updated.  If 
no  database  file  is  in  USE,  LUPDATEQ  returns  a  blank  date. 


Examples 

Tb  make  sure  that  receipts  are  not  entered  more  than  once  a  day,  include  the 
following  lines  in  a  data  entry  program: 

IF  UPDATED  <  DATEO 
Dajntry  =  "? 

3  5,1  SAY  'Receipts  were  last  entered  on  ’  +  DTOC(LLFDATEO)+; 

'  Biter  ncW?  CY/NT  GET  Dqjntry  PICTIRE  "T 

READ 

IF  Dojntry  *  mT 

DO  <entry  prccedre> 

BOIF 
BO  IF 


See  Also 

DBFQ,  DTOC(),  FIELD(),  MDXQ,  NDX(),ORDER(),  RECCOUNTQ,  RECSIZEQ, 
TAGQ 


LANGUAGE  REFERENCE 
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MAX() 


The  MAX()  function  returns  the  larger  of  two  numeric  or  date  expressions. 

Syntax 

MAX( <  expNl  >  ,<  exp2N>  ) 

Usage 

The  MAX()  function  compares  two  numeric  expressions,  returning  the  larger  of 
the  two.  In  the  case  of  dates,  it  returns  the  later  of  the  two. 

This  function  is  different  from  the  aggregate  MAX  function  used  with  the 
CALCULATE  command.  See  the  CALCULATE  command  for  a  description  of  the 
aggregate  MAX  function. 

Example 

To  determine  the  greater  of  two  values: 

.  first  =  12.32 

12.2 

.  second  -  Si.  12 
34.12 

.  ?  MfXC first,  second) 

34.12 


See  Also 

CALCULATE,  MIN() 


4-78 


FUNCTIONS 


PACE:  79  SE88:  14  Fr l  M.r  25  15:31:28  1988 
sk2/al  I  jobz/CLS_ptanhat/GRP_manhat/JOB.j»ian  I  angref /0IV_lrchap4 


MDX() 


The  MDX()  function  returns  the  filename  for  the  .mdx  file  specified  by  the 
index  order  number. 


Syntax 

MDX(<  expN>  [,<  alias  name>  ]) 


Usage 

This  function  returns  the  filename  for  the  mdx  directory  in  the  mdx  file  list. 

<  expN >  is  a  numeric  expression  specifying  the  mdx  file  position.  It  returns  a 
null  string,  if  there  is  no  list  of  .mdx  files  or  there  is  no  mdx  file  associated 
with  the  number  you  specified. 


See  Also 

KEY(),  NDXQ,  ORDERQ,  TAG<) 


LANGUAGE  REFERENCE 
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The  MDY()  function  converts  the  date  format  to  Month  Day,  Year. 

Syntax 

MDY( <  expD>  ) 

Usage 

The  MDY()  function  converts  any  date  to  a  Month  (full  name  of  month)  Day 
(two  digits),  Year  (two  digits)  format.  If  SET  CENTURY  is  ON,  four  digits  are 
displayed  for  the  year. 

This  function  returns  the  date  as  a  character  expression. 

Example 

To  display  02/29/88  in  MDY()  format: 

.  Leapcbte  -  (D2/2P/83} 

warn 

.  ?  leapcbte 
C2S29/& 

<  SETCRmjRfCN 
.  ?  H)Y(leapcbte) 

February  29,  1988 

See  Also 

DMY(),  SET  CENTURY,  SET  DATE,  SET  MARK 
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MEMLINES() 


The  MEMLINES()  function  returns  the  number  of  lines  contained  in  a  memo 
field,  when  word  wrapped  at  the  current  SET  MEMOWIDTH  value. 


Syntax 

MEMLINES(<  memo  field  name>  ) 


Usage 

This  function  uses  the  memo  width  setting  established  with  the  SET 
MEMOWIDTH  command,  to  determine  the  number  of  lines  in  a  memo  field. 


Example 

This  example  shows  the  interaction  between  the  SET  MEMOWIDTH  TO  com¬ 
mand  and  the  number  of  lines  of  text  that  the  MEMLINES()  function  returns. 
SET  MEMOWIDTH  changes  the  word  wrap  position;  therefore,  the  number  of 
lines  of  text  changes  accordingly. 

Assume  that  there  is  a  memo  field  called  Mary_mem  containing  the  text: 

Mary  had  a  little  lamb,  whose  fleece  was  white  as  snow. 

.  SET  tEKMDTH  TO  20 
.  ?  fary_jncm 
Vary  had  a  little 
lant>,  Uxse  fleece 
was  white  as  ax w. 

.  ?  mLDCSQtoryjjmtO 
3 

.  SET  N-KJJIDTH  TO  30 
.  ?  Msryjncm 

Very  had  a  little  lanb,  tixse 
fleece  mb  viiite  as  axw. 

.  ?  fGUNESO%ry_jm) 

2 


See  Also 

MLINEQ,  SET  MEMOWIDTH 


LANGUAGE  REFERENCE 
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MEMORY() 


The  MEMORY()  function  returns  the  amount  of  RAM  presently  unused. 


Syntax 

MEMORY([0]) 

Usage 

This  function  returns  the  number  of  1024-byte  increments  (kilobytes)  of  RAM 
available. 

Use  this  function  to  check  the  amount  of  available  memory  before  running 
applications  with  menus,  windows,  and  arrays  that  require  additional  memory, 
or  before  you  use  the  RUN/!  command  to  execute  DOS  commands  and 
programs. 

The  MEMORYQ  function  does  not  require  any  parameters;  it  returns  the  same 
value  with  or  without  the  optional  0  argument. 


Example 

This  example  uses  the  MEMORY()  function  to  test  if  there  is  sufficient  memory 
to  load  Command.com  before  issuing  the  RUN  command: 

IF  fCCRYO  <  25 

?  "There  isn't  enou^i  memory  to  Lead  CanraTd.com." 

ELSE 

RLN  CCPT  Acct_rec.cbf  A: 

BOIF 


See  Also 

DISKSPACEO,  GETENVQ,  0S() 
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MENUQ 


The  MENU()  function  returns  the  name  of  the  active  menu. 

Syntax 

MENUQ 

Usage 

This  function  returns  the  alphanumeric  string  for  the  name  of  the  last  menu 
that  was  activated.  If  there  is  no  active  menu,  this  function  returns  a  null  string. 


Example 

If  the  name  of  the  menu  that  was  last  activated  and  is  still  active  is  Utility,  use 
the  MENUQ  function  to  confirm  this. 

.  ?  tmjo 

Utility 

See  Also 

ACTIVATE  MENU,  DEFINE  MENU 


LANGUAGE  REFERENCE 
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MESSAGE() 


The  MESSAGE()  function  returns  the  message  corresponding  to  the  error 
which  caused  an  ON  ERROR  condition. 


Syntax 

MESSAGEQ 

Usage 

The  error  message  returned  by  the  MESSA3E()  function  can  be  displayed  on 
the  screen  or  stored  to  a  variable. 

See  Appendix  A  for  a  list  of  all  error  messages  generated  by  dBASE  IV  in 
single-user  operation. 

Error  messages  generated  by  dBASE  IV  on  a  local  area  network  are  described 
in  the  Networking  with  dBASE  /V  manual. 


See  Also 

ERROR(),  ON  ERROR 
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